Database

Managed Postgres (16, 17 or 18) for a project, on its private network, that sleeps when nothing asks anything of it and wakes with a connection. Made of a Cube's stateful service and a Drive, which the database changes alone. Not open to accounts yet.

הדף הזה עדיין לא תורגם לעברית: הנה הוא באנגלית.

Not open yet. Database is not open to accounts yet. These pages say how it works as it is built, ahead of its opening, and may change before then.

A database is a managed PostgreSQL of your project’s: version 16, 17 or 18, reached by its name on the project’s private network. It is made of what the platform already has: a Drive holds its data, and a stateful Cube service runs PostgreSQL on it. When nothing asks anything of it, its instance sleeps; a connection wakes it, with its sessions.

When to use Database

A Postgres for an app: your Cubes and sandboxes connect to it on the project’s network, by its name.
A database per environment, user or agent: one call makes one, and one call deletes it, keeping a snapshot of its data for a week.
Postgres with what apps reach for: vectors, PostGIS, time series, cron and full-text search come with it (PostgreSQL).

How it works

Make. POST /v1/databases with a name makes the Drive and the service, waits for PostgreSQL’s first start, and answers with the owner’s password and the connection string. The password is in that answer alone.
Connect. The project’s sandboxes on its network, and its services, connect with the connection string (private_uri): postgresql://<owner>:<password>@<name>:5432/<database>.
Sleep. After sleep_after_seconds with nothing asked of it (1 unless you say), its instance sleeps, with its memory and its sessions. A connection wakes it.
Delete. DELETE /v1/databases/{id} stops PostgreSQL, keeps a snapshot of its Drive for seven days, and deletes the rest.

POST /v1/databases
{"name": "shop", "version": "17"}

The calls

Call	What it does
`POST /v1/databases`	Makes a database (201); or answers the project’s database of the name (200), without its password, where the create asks for what it is.
`GET /v1/databases`, `GET /v1/databases/{id}`	The project’s databases, the newest first (`name` finds one); one, by its id or its name. Never a password.
`DELETE /v1/databases/{id}`	Deletes it, keeping a snapshot of its data for seven days (`?final_snapshot=false`: none).
`GET /v1/databases/{id}/branches`, `GET /v1/databases/{id}/branches/{branch}`	Its branches: its root branch, `main`, alone yet.
`POST /v1/databases/{id}/branches/{branch}/sleep`, `…/wake`	Puts its instance to sleep now; wakes it now.
`POST /v1/databases/{id}/roles/{role}/reset-password`	A new password for its owner, in the answer alone.

Making, deleting, sleeping, waking and a new password take a key with the write scope; reading, read.

Making a database

Every field but name may be left out:

Field	What it is
`name`	Lower-case letters, digits and hyphens: its name in the project and on its network. Its service has the name too, and its Drive is `<name>-data`: a name an app or a Drive has is refused (409 `name_taken`).
`version`	PostgreSQL’s major version: `16`, `17` or `18`, the default.
`region`	`na`, `eu` or `ap`; the project’s home where none is given.
`database_name`	The database in the cluster: `glacdb` unless you say. A lower-case identifier of at most 57 characters, not `postgres`, `template0`, `template1` nor `pg_…`. Its owner is `<database_name>_owner`.
`size`	`{vcpus, memory_bytes}`: its instance’s upper bounds, held to your plan’s, 1 vCPU and 1 GiB unless you say (256 MiB at the least). What it uses is billed, not these.
`storage`	`{size_bytes, durability}`: its Drive. `durability` is `strict` unless you say: a commit returns once the object store has it, so an answered commit outlives its machine. `standard`: once the machine has it.
`sleep_after_seconds`	How long its instance stays awake with nothing asked of it: 1 to 3,600 on Paid, 1 unless you say. On Free it is 1, fixed: Free’s database is paused a second after its last query and sleeps five minutes later, as Neon’s Free does (another value is refused, 400 `invalid_field`).
`metadata`	Keys and values of your own, strings.

The create waits for PostgreSQL’s first start (150 seconds at the most) and answers the database ready, or creating where its first start goes on: then GET it until it is ready. A create is idempotent by name: one that names a database of the project answers that one (200, without its password) where it asks for what it is, and is refused (409 name_taken) where it asks for something else. The Drive and the service count against what your plan lets a project keep, as any Drive and app do, and a refusal of either is the create’s, which undoes what it made.

What a database has

Field	What it is
`id`, `name`, `version`, `region`	`db-…`; as it was made. `region` is `null` where it is the project’s home.
`status`	`creating`, `ready`, `failed` (its first start failed: `error` says why, and it can only be deleted), `deleting`, `deleted`.
`database_name`, `role`	The database in the cluster, and its owner.
`password`	The owner’s password, in the answers to a create and to a new password alone; `null` everywhere else. It is kept nowhere: PostgreSQL holds a SCRAM verifier of it.
`default_branch`	Its root branch, `main`: `state` (`awake`, `paused` while it is held in the machine’s memory, `asleep`, `unavailable` while its machine cannot be reached; `creating`, `failed`), `private_host` (its name), `private_uri`, `size`, `storage` (its Drive’s `drive_id`, size and durability), `app_id` and `instance_id`.
`sleep_after_seconds`, `metadata`, `created_at`	As it was made.
`final_snapshot`	Of a deleted one: the snapshot of its Drive kept, and when it is deleted.

private_uri carries the password only in the answers that give it. The instance is a sandbox: GET /v1/sandboxes/{instance_id} reads it, and a command can be run in it.

Connecting

The project’s services, and its sandboxes on the project’s network (project_network: true), reach a database at its name (or <name>.internal), port 5432, with the owner and the password:

psql "postgresql://glacdb_owner:<password>@shop:5432/glacdb"

A connection to a sleeping database wakes it, as any connection to a service on the network does. Every login is by password (SCRAM); PostgreSQL’s superuser logs in on the machine alone, never over the network. POST /v1/databases/{id}/roles/{role}/reset-password (the role is its role) sets a new one: the old one is refused from the next login on, and a connection that is open stays.

Sleep and wake

Its instance sleeps after sleep_after_seconds with nothing asked of it, with its memory: the sessions open then are there when it wakes. A client that waits on it is something asked: while a query is under way (whatever it waits for, a lock or a timer among them), a transaction is left open or a login is not over, it stays awake, and is billed awake, until they end; an open connection that waits for nothing keeps it up no more than before. A connection wakes it; so does POST /v1/databases/{id}/branches/main/wake, held to what your plan lets the account have awake at once, as any wake is. …/sleep puts it to sleep now, whatever its clients wait for: a connection that is open stays open, its next message wakes it, and a question it had not answered is answered when it next wakes. A database being made or deleted is refused both (409 database_busy, retryable), and one whose first start failed, 409 database_failed.

If PostgreSQL stops by itself (it crashes, or the kernel’s OOM killer ends it), it is started again in its instance with its data as it was: it recovers as after a power cut, by its write-ahead log, and every committed transaction is there. It starts 0.1 seconds after its last process is gone, and waits twice as long each time it stops again within 10 seconds of starting, up to a minute. Each start is an event instance.restarted, and the branch’s start_command says how often it was started again, how it last ended and, while it waits, when it starts next (Services).

What a database is made of

A database’s service and Drive are the project’s: GET /v1/apps and GET /v1/drives list them, with managed_by naming the database ({"object": "database", "id": "db-…"}), and their logs, metrics and snapshots are read as any. Only the database changes them: an update, a deploy, a rollback or a delete of its app, a rename, restore or delete of its Drive, a read-write mount of its Drive anywhere else, and a delete or change of its instance are refused (409 managed_by_database). Snapshots of its Drive are anybody’s in the project to take, fork and mount read-only.

Until Database has meters of its own, a database is billed as what it is made of: its instance’s CPU time and memory as any instance’s (Sandbox prices), and its Drive as any Drive (Drive prices).

Deleting

DELETE /v1/databases/{id} deletes its service (PostgreSQL stops with a fast shutdown), takes a snapshot of its Drive at rest, the last state of its data, and deletes the Drive. The snapshot is kept seven days, as a Drive snapshot of the project’s (GET /v1/drive-snapshots?drive_deleted=true), which can be forked into a new Drive or mounted read-only; ?final_snapshot=false keeps none. The answer is the database deleted, with final_snapshot, or deleting where what is left takes longer, which the platform finishes. The name is free at once.

PostgreSQL: the versions, the extensions, the roles and what the owner may do, how a new database begins, its compression, and the settings the platform keeps.