尚未开放。数据库还没有向账户开放。这些页面按目前正在构建的样子介绍它，开放前可能还会变化。
数据库是你项目中的托管 PostgreSQL：版本 16、17 或 18，在项目的私有网络上按名称访问。它由平台已有的东西构成：一个云盘保存它的数据，一个有状态的方块服务在上面运行 PostgreSQL。没有任何请求时，它的实例休眠；连接会唤醒它，会话都还在。
什么时候用数据库
- 给应用用的 Postgres：你的方块和沙箱在项目网络上按名称连接它。
- 每个环境、用户或智能体一个数据库：一次调用创建一个，一次调用删除它，并把它的数据快照保留一周。
- 带有应用常用功能的 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，把它的云盘快照保留七天，并删除其余部分。
POST /v1/databases
{"name": "shop", "version": "17"}调用
| 调用 | 作用 |
|---|---|
POST /v1/databases |
创建一个数据库 (201)；或者，在创建请求所要求的内容与已有数据库一致时，返回项目中同名的数据库 (200)，不带密码。 |
GET /v1/databases, GET /v1/databases/{id} |
项目的数据库，最新的在前（用 name 查找）；按 id 或名称查看一个。从不包含密码。 |
DELETE /v1/databases/{id} |
删除它，并把它的数据快照保留七天（?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 的免费版相同（其他值会被拒绝，400 invalid_field）。 |
metadata |
你自己的键和值，都是字符串。 |
创建请求会等待 PostgreSQL 第一次启动（最多 150 秒），然后返回处于 ready 的数据库；如果第一次启动仍在进行，则返回 creating：这时反复 GET 它，直到它变成 ready。创建按名称保证幂等：指定项目中已有数据库的创建请求，如果要求的内容与它一致，就返回它（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)，用所有者和密码，在 5432 端口按名称（或 <name>.internal）访问数据库：
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 秒内再次停止，等待时间就加倍，最多一分钟。每次启动都是一个 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 以快速关闭方式停止），在云盘静止时为它创建快照，即数据的最终状态，然后删除云盘。快照保留七天，作为项目中的一个云盘快照 (GET /v1/drive-snapshots?drive_deleted=true)，可以分叉成新云盘，也可以以只读方式挂载；?final_snapshot=false 则不保留。响应是处于 deleted 的数据库，带有 final_snapshot；剩余部分需要更久时，返回 deleting，平台会完成删除。名称立即可以再用。
下一步
- PostgreSQL：版本、扩展、角色及所有者能做什么、新数据库如何开始、它的压缩，以及平台保留的设置。