**未公開。**データベースはまだ利用できません。これらのページは、構築中の仕組みを公開前に説明したもので、公開までに変わることがあります。
データベースは、プロジェクト専用のマネージド PostgreSQL です。バージョンは 16、17、18 のいずれかで、プロジェクトのプライベートネットワーク上で、その名前で接続します。プラットフォームにすでにあるものから作られており、ドライブがデータを保持し、ステートフルなキューブのサービスがその上で PostgreSQL を動かします。何も要求がないときはインスタンスがスリープし、接続があればセッションを保ったまま復帰します。
データベースを使う場面
- アプリのための Postgres：キューブとサンドボックスが、プロジェクトのネットワーク上で、その名前で接続します。
- 環境、ユーザー、エージェントごとのデータベース：1 回の呼び出しで作成し、1 回の呼び出しで削除できます。削除時にはデータのスナップショットを 1 週間保持します。
- アプリがよく使う機能を備えた Postgres：ベクトル、PostGIS、時系列、cron、全文検索が最初から使えます（PostgreSQL）。
仕組み
- **作成。**名前を付けた
POST /v1/databasesで、ドライブとサービスが作られ、PostgreSQL の最初の起動を待って、オーナーのパスワードと接続文字列が返されます。パスワードが含まれるのは、このレスポンスだけです。 - **接続。**プロジェクトのネットワーク上にあるサンドボックスとプロジェクトのサービスは、接続文字列（
private_uri）で接続します：postgresql://<owner>:<password>@<name>:5432/<database>。 - **スリープ。**何も要求がない状態が
sleep_after_seconds秒続くと（指定しなければ 1 秒）、インスタンスはメモリとセッションを保ったままスリープします。接続があれば復帰します。 - 削除。
DELETE /v1/databases/{id}は PostgreSQL を止め、ドライブのスナップショットを 7 日間保持し、残りを削除します。
POST /v1/databases
{"name": "shop", "version": "17"}呼び出し一覧
| 呼び出し | 内容 |
|---|---|
POST /v1/databases |
データベースを作成（201）。または、作成の指定内容が既存のものと同じなら、その名前のプロジェクトのデータベースを、パスワードなしで返す（200） |
GET /v1/databases, GET /v1/databases/{id} |
プロジェクトのデータベースの一覧（新しい順。name で 1 つを検索）。ID または名前で指定した 1 つのデータベース。パスワードは含まない |
DELETE /v1/databases/{id} |
データのスナップショットを 7 日間保持して削除（?final_snapshot=false なら保持しない） |
GET /v1/databases/{id}/branches, GET /v1/databases/{id}/branches/{branch} |
ブランチの一覧。現時点ではルートブランチの main だけ |
POST /v1/databases/{id}/branches/{branch}/sleep, …/wake |
インスタンスをすぐにスリープさせる。すぐに復帰させる |
POST /v1/databases/{id}/roles/{role}/reset-password |
オーナーの新しいパスワードを発行。パスワードはレスポンスにだけ含まれる |
作成、削除、スリープ、復帰、新しいパスワードの発行には write スコープを持つキーが、読み取りには read スコープが必要です。
データベースの作成
name 以外のフィールドは省略できます。
| フィールド | 説明 |
|---|---|
name |
英小文字、数字、ハイフン。プロジェクト内とネットワーク上での名前。サービスも同じ名前を持ち、ドライブは <name>-data。アプリやドライブがすでに使っている名前は拒否される（409 name_taken） |
version |
PostgreSQL のメジャーバージョン：16、17、18（デフォルト） |
region |
na、eu、ap のいずれか。指定しなければプロジェクトのホームリージョン |
database_name |
クラスター内のデータベース。指定しなければ glacdb。57 文字以内の小文字の識別子で、postgres、template0、template1、pg_… は使えない。オーナーは <database_name>_owner |
size |
{vcpus, memory_bytes}：インスタンスの上限。プランの上限内で、指定しなければ 1 vCPU と 1 GiB（最小 256 MiB）。課金されるのはこの値ではなく使用量 |
storage |
{size_bytes, durability}：ドライブ。durability は指定しなければ strict で、コミットはオブジェクトストアに届いてから戻るため、応答したコミットはマシンが失われても残る。standard ならマシンに届いた時点で戻る |
sleep_after_seconds |
何も要求がない状態でインスタンスが稼働したままでいる時間：有料プランでは 1〜3,600 秒、指定しなければ 1 秒。無料プランでは 1 秒で固定。Neon の無料プランと同じく、無料プランのデータベースは最後のクエリの 1 秒後に一時停止し、その 5 分後にスリープする（ほかの値は 400 invalid_field で拒否される） |
metadata |
任意のキーと値（文字列） |
作成は PostgreSQL の最初の起動を待ち（最大 150 秒）、データベースを ready で返します。最初の起動が続いている場合は creating で返すので、ready になるまで GET してください。作成は名前によって冪等です。プロジェクトのデータベースの名前を指定した作成は、指定内容が同じならそのデータベースを返し（200、パスワードなし）、違えば拒否されます（409 name_taken）。ドライブとサービスは、ほかのドライブやアプリと同じく、プランでプロジェクトが保持できる数の上限に数えられ、そのどちらかが拒否されると作成が拒否され、作ったものは元に戻されます。
データベースが持つもの
| フィールド | 説明 |
|---|---|
id, name, version, region |
db-…。作成時のとおり。プロジェクトのホームリージョンなら region は null |
status |
creating、ready、failed（最初の起動に失敗。error に理由が入り、削除しかできない）、deleting、deleted |
database_name, role |
クラスター内のデータベースと、そのオーナー |
password |
オーナーのパスワード。作成と新しいパスワードの発行に対するレスポンスにだけ含まれ、それ以外では null。どこにも保存されず、PostgreSQL はその SCRAM ベリファイアを保持する |
default_branch |
ルートブランチ main：state（awake、マシンのメモリ上に保持されている間は paused、asleep、マシンに到達できない間は unavailable、creating、failed）、private_host（名前）、private_uri、size、storage（ドライブの drive_id、サイズ、耐久性）、app_id、instance_id |
sleep_after_seconds, metadata, created_at |
作成時のとおり |
final_snapshot |
削除済みのデータベースの場合：保持されているドライブのスナップショットと、それが削除される日時 |
private_uri にパスワードが含まれるのは、パスワードを返すレスポンスだけです。インスタンスはサンドボックスなので、GET /v1/sandboxes/{instance_id} で読み取ることができ、中でコマンドを実行することもできます。
接続
プロジェクトのサービスと、プロジェクトのネットワーク上にあるサンドボックス（project_network: true）は、データベースの名前（または <name>.internal）のポート 5432 に、オーナーとパスワードで接続します。
psql "postgresql://glacdb_owner:<password>@shop:5432/glacdb"スリープ中のデータベースは、ネットワーク上のサービスへのほかの接続と同じく、接続があると復帰します。ログインはすべてパスワード（SCRAM）で行います。PostgreSQL のスーパーユーザーはマシン上でしかログインできず、ネットワーク経由でログインすることはありません。POST /v1/databases/{id}/roles/{role}/reset-password（ロールはデータベースの role）で新しいパスワードを設定します。古いパスワードは次のログインから拒否され、開いている接続はそのままです。
スリープと復帰
インスタンスは、何も要求がない状態が sleep_after_seconds 秒続くと、メモリを保ったままスリープします。そのとき開いていたセッションは、復帰したときにもそのまま残っています。インスタンスを待っているクライアントは要求とみなされます。クエリの実行中（ロックやタイマーなど、何を待っていても）、トランザクションが開いたまま、またはログインが終わっていない間は、それが終わるまで稼働し続け、稼働中として課金されます。何も待っていない開いた接続は、これまでどおり稼働を延ばしません。接続があれば復帰し、POST /v1/databases/{id}/branches/main/wake でも復帰します。この復帰も、ほかの復帰と同じく、プランでアカウントが同時に稼働させられる上限の対象です。…/sleep は、クライアントが何を待っていても、すぐにスリープさせます。開いている接続は開いたままで、次のメッセージで復帰し、応答していなかった問い合わせには、次に復帰したときに応答します。作成中または削除中のデータベースではどちらも拒否され（409 database_busy、retryable）、最初の起動に失敗したデータベースでは 409 database_failed で拒否されます。
PostgreSQL が自ら停止した場合（クラッシュ、またはカーネルの OOM killer による終了）は、データをそのままにして、インスタンスの中で再起動されます。停電の後と同じように先行書き込みログで復旧し、コミット済みのトランザクションはすべて残っています。最後のプロセスがなくなってから 0.1 秒後に起動し、起動から 10 秒以内に再び停止するたびに、待つ時間を 2 倍にします（最大 1 分）。起動のたびにイベント instance.restarted が発生し、ブランチの start_command が、再起動の回数、最後の終わり方、そして待機中なら次に起動する時刻を示します（サービス）。
データベースの構成
データベースのサービスとドライブはプロジェクトのものです。GET /v1/apps と GET /v1/drives はそれらを、データベースを示す managed_by（{"object": "database", "id": "db-…"}）とともに一覧表示し、ログ、メトリクス、スナップショットはほかと同じように読めます。変更できるのはデータベースだけです。アプリの更新、デプロイ、ロールバック、削除、ドライブの名前の変更、復元、削除、ほかの場所での読み書き可能なマウント、インスタンスの削除と変更は拒否されます（409 managed_by_database）。ドライブのスナップショットは、プロジェクトの誰でも取得、フォーク、読み取り専用でのマウントができます。
データベース独自の計測項目ができるまでは、データベースは構成するものとして課金されます。インスタンスの CPU 時間とメモリはほかのインスタンスと同じく（サンドボックスの料金）、ドライブはほかのドライブと同じく（ドライブの料金）課金されます。
削除
DELETE /v1/databases/{id} は、サービスを削除し（PostgreSQL は高速シャットダウンで停止）、静止状態のドライブのスナップショット（データの最後の状態）を取ってから、ドライブを削除します。スナップショットはプロジェクトのドライブのスナップショットとして 7 日間保持され（GET /v1/drive-snapshots?drive_deleted=true）、新しいドライブにフォークしたり、読み取り専用でマウントしたりできます。?final_snapshot=false なら何も保持しません。レスポンスは final_snapshot 付きの deleted のデータベースで、残りの処理に時間がかかる場合は deleting となり、プラットフォームがそれを完了させます。名前はすぐに解放されます。
次のステップ
- PostgreSQL：バージョン、拡張機能、ロールとオーナーができること、新しいデータベースの始まり方、圧縮、プラットフォームが維持する設定。