# Database lifecycle states

> Database states, connection availability, persistence and deletion blockers

> Nevia is in beta and open to selected teams. Public launch in Dec 2026. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser.
> Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md).

> For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/reference/database-lifecycle

For the procedures, see [Create and connect to a database](https://nevia.cloud/docs/databases/create.md),
[Branch a database](https://nevia.cloud/docs/databases/branch.md), and
[Sleep, wake and delete a database](https://nevia.cloud/docs/databases/lifecycle.md).

## States

`state` describes the database now. `pending` names the state a transition is
driving toward; `null` means no transition is pending.
[`nevia pg status`](https://nevia.cloud/docs/reference/cli/pg/status.md) 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](https://nevia.cloud/docs/reference/operations.md) 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`](https://nevia.cloud/docs/reference/cli/pg/connect.md) 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](https://nevia.cloud/docs/reference/api/databases/createDatabase.md) for
request fields and the [workspace permissions](https://nevia.cloud/docs/reference/workspace-permissions.md)
required for database actions.