Database states, connection availability, persistence and deletion blockers
For the procedures, see Create and connect to a database, Branch a database, and Sleep, wake and delete a database.
States
state describes the database now. pending names the state a transition is
driving toward; null means no transition is pending.
nevia pg status shows a pending target with an
arrow, such as ready (→ sleeping).
| State | Meaning |
|---|---|
creating | The database or branch is starting. |
ready | The guest reports readiness. Check SQL access using the TLS connection URI. |
sleeping | The microVM is paused with RAM allocated; SQL connections are unavailable. |
failed | Creation or a lifecycle action failed. Read the error field. |
deleting | Deletion is in progress. |
deleted | Deletion is complete; the database is no longer available in normal reads. |
ready does not prove that the endpoint is reachable from your client or that
its TLS configuration works. A successful SQL query using the returned URI checks
that path.
Transitions
Sleep, wake and branch require an existing microVM, pending: null, and no
operation running on the source. Wait for a pending transition or reported
operation before retrying.
| Action | Required starting state | While in progress | Successful result |
|---|---|---|---|
| Create | No existing database with that name. | creating, pending ready | A new ready database. |
| Sleep | ready | ready, pending sleeping | The same database becomes sleeping. |
| Wake | sleeping | sleeping, pending ready | The same database becomes ready. |
| Branch | Source is ready or sleeping. | New database is creating, pending ready. | A new ready database; the source keeps its state. |
| Delete | A live database, subject to the blockers below. | deleting, pending deleted | The database and its data are removed. |
Failures can leave a database in failed. Sleep on an idle sleeping database
and wake on an idle ready database return it unchanged.
Sleep and wake can finish within the request without returning an operation. When they need more time, the response includes an operation and pending target. See the operation reference for shared wait behavior.
Connections and credentials
Every database runs the platform's managed Postgres (currently 18.6) with a fixed
size and 20 GiB of storage. The user is nevia_admin on database nevia, and a
connection pooler listens on port 6432 of the same host.
The platform sets the password and keeps it; the control plane never stores it.
Creation returns it when the database is ready before the request answers;
otherwise the response has no connection. A replay with the same idempotency key
has none either. Resource reads and lists omit credentials.
nevia pg connect reads the connection at any
time the database is ready or sleeping; it prints connection details without
opening a SQL session. Other states answer 409 invalid_state, and so does a
branch for a few seconds after it becomes ready while its credentials are set up.
password_status is tracked or untracked. If you change the password in SQL,
the platform no longer knows it: the connection reads untracked, with no
password and a URI that carries only the user. It stays that way until you reset
the credentials, which sets a new tracked password and stops the old one working.
A reset on a sleeping database applies when it wakes: until then the connection
reports reset_pending with no password.
Connection URIs require TLS, with sslmode=require or stricter. The host is the
name the platform assigns once the database is first ready.
SQL access is unavailable while sleeping. Open a new connection after wake, using the same credentials. Status and credential reads do not wake the database.
Persistence and branches
Sleep calls Ember Machines/Pause, retaining RAM without taking a snapshot; wake
calls Machines/Resume. Sleep does not require snapshot support and is not a backup.
| Action | Data | Identity and credentials |
|---|---|---|
| Sleep, then wake | Kept, with memory retained in RAM and resumed at wake. | Same database ID, host and credentials. |
| Branch | Private copies of the source's data disks. Writes on the branch do not change the source. | New ID, host and password. The branch records the source as parent. |
| Delete | Removed. | The database is no longer available. |
A branch has the source's Postgres version. A branch of a running or paused
source starts Postgres from the cloned disks with fresh memory. Older machines
suspended to disk also appear as sleeping; a branch of one restores its saved
memory and paired disks. The current CLI pg suspend command pauses in memory
instead.
A running source can reuse a disk snapshot less than five seconds old. To include fresh writes, commit them and wait at least five seconds before branching. A fresh snapshot briefly freezes writes to the data filesystem.
Deletion blockers
Deletion requires protected: false and no running operation. Deleting a parent
leaves its branches running with their own data. Each branch's parent field
continues to name the deleted database's ID.
Protection blocks deletion without blocking sleep, wake or branch. New branches are unprotected unless you request protection; they do not inherit the parent's setting. Renaming and changing protection take effect without a restart or operation.
Database checkpoints and restoration from checkpoints are not supported in this build. See the database API reference for request fields and the workspace permissions required for database actions.