Databases API

List the database engines and versions that can be created

Create a managed database

Creates a staged database service with its data volume and generated credentials; nothing runs until it is deployed. Other services connect with ${{<slug>.DATABASE_URL}} (or REDIS_URL, MONGO_URL).

Get a managed database's engine, exports and state

Promote a read replica to primary (manual)

Called on the replica. Manual: NebulaCtrl does not detect failures or switch automatically. With dryRun the plan is returned (status 200): switchover while the old primary is reachable (it is frozen, stopped and fenced, the replica replays everything, no data is lost) or forced otherwise (it needs acceptDataLoss: what the replica had not received is lost). The old primary is fenced and never runs as a primary again; rebuild it as a replica or delete it. Variables that reference the old primary are rewritten as staged changes. Production environments need approval. Asynchronous: poll replication.promotion.

Get a database's public port

Publish (or change) a database's public port

Stages a TCP route on listenPort of the database's server with a mandatory IP allow-list and an optional deny list (deny first). 0.0.0.0/0 or ::/0 is accepted only with confirmOpen set to the database slug. The proxy forwards raw TCP and never terminates TLS. Nothing changes until the route is deployed; a new port recreates the proxy container (about a second of dropped connections). Needs projects:write and proxy:write. 422 codes: allowlist_required, open_confirmation_required, invalid_config, invalid_listen_port, no_server, agent_too_old. 409 port_in_use.

Close a database's public port

Deletes the route service. A deployed route disappears from the server's table at once.

Reveal the external connection string (audited)

Like revealDatabaseExport, but with the server's public IP and the public port instead of the private host. Needs deployments:write, is uncached and recorded as secret.reveal. 409 public_port_disabled; 422 no_public_address when the server has no public IP.

Rebuild a replica, or a fenced old primary as a replica

Clones the primary again into a new data volume (the old volume is kept until it is deleted). On a fenced old primary the body may name the new primary to follow. Asynchronous.

Ask the agent for the database's version, size and connections

Asynchronous: poll GET /services/{id}/database (or watch the event feed) for the new info.

Remove a read replica

Called on the replica. Deletes its container and data volume, drops its slot, role and pg_hba.conf line on the primary and releases its mesh link. Asynchronous.

Add a read replica of a PostgreSQL primary

Creates a read replica service in the primary's environment and clones the primary into it. The replica runs on the primary's server or, with the server mesh enabled on both, on another server. Asynchronous: the replica is pending, then preparing, cloning, deploying and streaming; follow it with GET /services/{id}/database/replication. With dryRun only the plan is returned (status 200). Replication is asynchronous and manual: nothing is detected or switched automatically.

Get the read replica group of a PostgreSQL database

Reveal a connection string (audited)

Returns one derived export such as DATABASE_URL in plain text, uncached. Requires the deployments:write scope (or admin) and is recorded in the audit log as secret.reveal. Every other read stays masked.

Rotate the database password

Changes the application password inside the running database through the agent (or, for Valkey and Redis, stages a new password), updates the variable and stages every service that references the database. Nothing is deployed. With dryRun only the plan is returned.

Upgrade the database version

In-place engines stage the new image. PostgreSQL majors are converted with pg_upgrade into a new volume (the old volume is kept) and the new version is staged when the conversion finishes. Take a backup first.

Plan a version upgrade