> ## 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、メモリ設定、よくあるエラー。

クライアント証明書による TLS 接続、自分専用のデータベースとロール、すぐに有効化できる定番の拡張機能、定期ジョブ用の `pg_cron` を備えたマネージド PostgreSQL インスタンスです。すべてのエンジンに共通する事項 (制限、snapshot、Insights) は[データベースの概要](https://docs.squarecloud.app/ja/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、GUI ツール) については、[データベース接続エラー](https://docs.squarecloud.app/ja/platform/troubleshooting/database-connection-errors.md)で説明しています。

## 接続数

各データベースは最大 256 の同時接続を受け付け、そのうち **253 がクライアント用**です。それを超えると、新しい接続は `remaining connection slots are reserved for roles with the SUPERUSER attribute` (または `sorry, too many clients already`) で失敗します。起動時に **プロセスごとに 1 つのプール**を作成して使い回し、すべてのアプリ、ワーカー、シャードの合計が上限を下回るようにサイズを決めてください。リクエストやクエリのたびに新しい接続を開くと、すぐに上限に達します。開いている接続を誰が保持しているかは **Insights** タブで確認できます。

## ユーザーと権限

`squarecloud` ロールは `LOGIN`、`CREATEDB`、`CREATEROLE`、`BYPASSRLS` を持ち、`squarecloud` データベースを所有しています。データベース、スキーマ、ロール、権限付与を作成でき、通常のユーザーが変更できる設定を、セッション単位またはデフォルトとして変更できます。

```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 つのクエリが書き込める一時ファイル (ソート、ハッシュ) は最大 **1 GB** です。それを超えるとクエリは `temporary file size exceeds temp_file_limit` で失敗します。インデックスを追加するか、データをバッチで処理してください。
* 先行書き込みログ (WAL) は、データベースのストレージのうち 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/ja/services/databases.md#snapshot-と復元)に加えて、`ALLOW_CONNECTIONS false` のデータベースがある場合や、自分のロック (`LOCK TABLE`、長時間の `ALTER TABLE`) が 5 分を超えてエクスポートをブロックした場合にも失敗します。エクスポートはプレーンな 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 の接続がすべて使用中です。 | プロセスごとに共有プールを 1 つ使います。[接続数](#接続数)を参照してください。 |
| `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/ja/platform/troubleshooting/database-performance.md#ディスクがいっぱい)を参照してください。 |
| `the database system is not yet accepting connections` | 強制停止のあと、データベースが復旧処理中です。 | 待ちます。復旧が終わると接続を受け付けます。 |

## お問い合わせ

**技術的な問題**が解決しない場合は、**専門のサポートチーム**がお手伝いします。[**お問い合わせ**](https://squarecloud.app/ja/support)いただければ、どのような問題でも喜んで解決をサポートいたします。サポートの質の高さも、開発者が Google と Trustpilot で Square Cloud に[**402 件のレビューで 4.9/5**](https://www.trustpilot.com/review/squarecloud.app)という評価をつけている理由の 1 つです。


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