> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Square Cloud 上的 PostgreSQL：连接、扩展与限制

> Square Cloud 上的托管 PostgreSQL：连接字符串、带客户端证书的 TLS、用户权限、可用扩展、pg_cron、内存设置以及常见错误。

一个托管的 PostgreSQL 实例：使用客户端证书的 TLS 连接、属于你自己的数据库和角色、随时可启用的常用扩展，以及用于定时任务的 `pg_cron`。所有引擎共有的信息（限制、snapshot、Insights）请参阅[数据库概览](https://docs.squarecloud.app/zh/services/databases.md)。

## 连接

从控制台中该数据库的页面复制连接 URL。它的形式如下，其中 `squarecloud` 用户和 `squarecloud` 数据库已为你创建好：

```
postgresql://squarecloud:PASSWORD@HOST:PORT/squarecloud
```

除了密码之外，PostgreSQL 还要求 **SSL/TLS 和客户端证书**。在 **连接** → **SSL/TLS 证书** 中下载 `.pem`，并让客户端指向它：

| 参数 | 值 |
| :- | :- |
| `sslmode` | `require`，或使用 `verify-ca` / `verify-full` 同时校验服务器 |
| `sslcert` | `.pem` |
| `sslkey` | `.pem` |
| `sslrootcert` | `.pem`（`verify-ca` 和 `verify-full` 需要） |

> [tab] Node.js
>
> ```javascript theme={"system"}
> import fs from "node:fs";
> import pg from "pg";
>
> const pem = fs.readFileSync("certificate.pem", "utf8");
>
> // One pool for the whole process, created once and reused.
> export const pool = new pg.Pool({
>   connectionString: process.env.DATABASE_URL,
>   ssl: { ca: pem, cert: pem, key: pem },
>   max: 10,
> });
>
> const { rows } = await pool.query("SELECT now()");
> ```

> [tab] Python
>
> ```python theme={"system"}
> import os
> import psycopg2
>
> # libpq refuses a key file that other users can read.
> os.chmod("certificate.pem", 0o600)
>
> conn = psycopg2.connect(
>     os.environ["DATABASE_URL"],
>     sslmode="verify-ca",
>     sslrootcert="certificate.pem",
>     sslcert="certificate.pem",
>     sslkey="certificate.pem",
> )
> ```

> [tab] psql
>
> ```bash theme={"system"}
> chmod 600 certificate.pem
> psql "postgresql://squarecloud:PASSWORD@HOST:PORT/squarecloud?sslmode=verify-ca&sslrootcert=certificate.pem&sslcert=certificate.pem&sslkey=certificate.pem"
> ```

> [!NOTE]
>
> Go 客户端在使用此证书时会拒绝 `sslmode=verify-full`（`x509: certificate relies on legacy Common Name field`）：该证书只在 Common Name 中写明主机名，而 Go 已不再检查这一字段。请使用 `sslmode=verify-ca`，它仍会校验证书。

ORM 和其他客户端（Prisma、Drizzle、JDBC、图形界面工具）的配置请参阅[数据库连接错误](https://docs.squarecloud.app/zh/platform/troubleshooting/database-connection-errors.md)。

## 连接数

每个数据库最多接受 256 个同时连接，其中 **253 个可供你的客户端使用**。超过之后，新连接会失败并提示 `remaining connection slots are reserved for roles with the SUPERUSER attribute`（或 `sorry, too many clients already`）。请在启动时为**每个进程创建一个连接池**并重复使用，连接池的大小要保证所有应用、worker 和分片加在一起都低于上限。每个请求或每次查询都新建连接，会很快耗尽上限。**Insights** 选项卡会显示是谁占用着这些打开的连接。

## 你的用户与权限

`squarecloud` 角色拥有 `LOGIN`、`CREATEDB`、`CREATEROLE` 和 `BYPASSRLS`，并且是 `squarecloud` 数据库的所有者。你可以创建数据库、schema、角色和授权，也可以修改普通用户允许修改的设置，作用于单个会话或作为默认值：

```sql theme={"system"}
ALTER ROLE squarecloud SET statement_timeout = '30s';
ALTER DATABASE squarecloud SET work_mem = '16MB';
```

该角色**不是超级用户**，也没有复制权限。因此以下操作不可用：

* `ALTER SYSTEM` 以及仅限超级用户的设置；
* 服务器端的 `COPY ... TO/FROM 'file'`（请改用 `psql` 中的 `\copy`，它在你的机器上读写文件）；
* 不受信任的语言，例如 `plpython3u`；
* 逻辑复制，以及依赖它的变更数据捕获工具。

## 扩展

已安装：`plpgsql`，以及 `postgres` 数据库中的 `pg_cron` 和 `pg_stat_statements`。

你可以在任意数据库中使用 `CREATE EXTENSION` 启用以下扩展，请在要使用它们的数据库中执行：

`vector`（pgvector）、`pg_trgm`、`pgcrypto`、`uuid-ossp`、`citext`、`hstore`、`unaccent`、`ltree`、`btree_gin`、`btree_gist`、`cube`、`dict_int`、`fuzzystrmatch`、`intarray`、`isn`、`lo`、`seg`、`tablefunc`、`tcn`、`tsm_system_rows`、`tsm_system_time`。

```sql theme={"system"}
CREATE EXTENSION IF NOT EXISTS vector;
```

没有其他可用的扩展，也无法按需添加。例如，PostGIS 不可用。

## 使用 pg\_cron 运行定时任务

`pg_cron` 位于 `postgres` 数据库中。连接到 `postgres`（同一个 URL，以 `/postgres` 结尾），然后安排任务在你的数据库中运行。计划时间使用 **UTC**：

```sql theme={"system"}
SELECT cron.schedule_in_database(
  'refresh-stats',          -- job name
  '*/5 * * * *',            -- every 5 minutes
  'REFRESH MATERIALIZED VIEW stats',
  'squarecloud'             -- database the job runs in
);

SELECT jobid, jobname, schedule, database FROM cron.job;
SELECT cron.unschedule('refresh-stats');
```

`cron.job_run_details` 中的运行历史永远不会被自动清理。请安排一个任务来清理你的旧记录：

```sql theme={"system"}
SELECT cron.schedule_in_database('purge-cron-history', '0 3 * * *',
  $$DELETE FROM cron.job_run_details WHERE end_time < now() - interval '7 days'$$, 'postgres');
```

## 内存与配置

* `shared_buffers` 为**数据库 RAM 的 25%**（至少 128 MB）。修改 RAM 会重启数据库以使其生效。
* 其余部分 PostgreSQL 依赖操作系统的文件缓存，因此控制台中显示的 RAM 会先上升然后保持在高位。这是正常现象，不是内存泄漏。
* 单个查询最多可以写入 **1 GB 的临时文件**（排序、哈希）。超过后查询会失败并提示 `temporary file size exceeds temp_file_limit`：请添加索引或分批处理数据。
* 预写日志（write-ahead log）占用数据库存储中的 256 到 512 MB。
* 服务器配置在每个数据库上都相同，无法针对单个数据库修改。

## 慢查询

耗时 100 ms 或以上的语句会被记录，**Insights** 选项卡会列出它们及其平均耗时。如需自行分析，请连接到 `postgres` 数据库查询 `pg_stat_statements`，并对语句使用 `EXPLAIN ANALYZE`：

```sql theme={"system"}
SELECT calls, round(mean_exec_time) AS mean_ms, query
FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;
```

## Snapshot

PostgreSQL 的 snapshot 包含实例中的所有数据库和角色。除了[通用情况](https://docs.squarecloud.app/zh/services/databases.md#snapshot-与恢复)之外，当某个数据库设置了 `ALLOW_CONNECTIONS false`，或者你自己的锁（`LOCK TABLE`、耗时较长的 `ALTER TABLE`）阻塞它超过 5 分钟时，snapshot 也会失败。导出内容是纯 SQL 文本，因此接近 10 GB 存储上限的数据库可能无法放进一个 snapshot。

## 常见错误

| 信息 | 含义 | 处理方法 |
| :- | :- | :- |
| `no pg_hba.conf entry for host ... no encryption` | 客户端未使用 SSL/TLS 连接。 | 启用 `sslmode` 并加载证书。 |
| `connection requires a valid client certificate` | 已启用 SSL/TLS，但未发送客户端证书。 | 将 `sslcert` 和 `sslkey` 设置为 `.pem`。 |
| `private key file ... has group or world access` | libpq（psql、psycopg2）拒绝可被他人读取的密钥文件。 | 对 `.pem` 执行 `chmod 600`（在 Python 中使用 `os.chmod(path, 0o600)`）。 |
| `remaining connection slots are reserved for roles with the SUPERUSER attribute` / `sorry, too many clients already` | 253 个连接已全部被占用。 | 每个进程使用一个共享连接池；参见[连接数](#连接数)。 |
| `must be superuser` / `permission denied to set parameter` | 该命令需要超级用户。 | 改用会话或角色级别的设置，或换一种方式。 |
| `extension "..." is not available` | 该扩展不在上面的列表中。 | 使用可用的扩展之一。 |
| `temporary file size exceeds temp_file_limit` | 查询需要超过 1 GB 的临时文件。 | 添加索引或分批处理。 |
| `could not extend file ... No space left on device` | 10 GB 存储已满：写入失败。 | 删除数据；参见[磁盘已满](https://docs.squarecloud.app/zh/platform/troubleshooting/database-performance.md#磁盘已满)。 |
| `the database system is not yet accepting connections` | 数据库在强制停止后正在恢复。 | 请等待：恢复结束后即可接受连接。 |

## 联系我们

如果你仍然遇到**技术问题**，我们的**专业支持团队**可以为你提供帮助。[**联系我们**](https://squarecloud.app/zh/support)，我们很乐意协助你解决任何问题，支持质量正是开发者给予 Square Cloud [**4.9/5 评分（共 402 条评价）**](https://www.trustpilot.com/review/squarecloud.app)（Google 与 Trustpilot）的重要原因之一。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.