Create and connect a database

A database service runs inside your cluster like any other service and is reachable only from inside it. This guide creates one, connects a service, and covers queries, readers, recovery and backups.

Before you beginCopy Anchor Link

• You have the deployer role to create, connect and query a database. Admin is needed to restore, to query or configure recovery in a production environment, and to take, schedule or download a backup in one.
• The environment is bound to a cluster. A PostgreSQL database also needs CloudNativePG on that cluster.
• Backups need an organization object store.

Create a databaseCopy Anchor Link

To create the database through the API, name the environment to stage its first deploy in:

curl -X POST "BASE_URL/api/v1/projects/PROJECT_ID/databases" \
  -H "Authorization: Bearer NEBULA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "postgres", "name": "main", "stageIn": {"environmentId": "ENVIRONMENT_ID"}}'

template is postgres, valkey, mysql or mongodb (listDatabaseTemplates). Without stageIn, nothing is staged.

Every database gets the newest major version, a 10 GiB volume, and one process with 250m–1 CPU and 256 MiB–1 GiB of memory.

To pick an older major or a size other than 10 GiB at creation, declare the database with version and size in the project file.

Connect a serviceCopy Anchor Link

To read the URL yourself, use the Connection row on the Data tab: Reveal shows it for 30 seconds, Hide hides it, Copy copies it. PostgreSQL also shows Read connection. Reveal needs the deployer role; without it, Copy gives the masked URL.

Connect writes only the main variable. To send reads to the reader endpoint svc-SLUG-read, add a variable on the service with the value ${{ SLUG.DATABASE_READ_URL }}. It points at the writer until the database has readers.

Run a queryCopy Anchor Link

On the Data tab, pick a table, collection or keyspace to preview five rows, or type in the Query box and select Run (Ctrl or ⌘ + Enter). Every query runs on the writer, stops after 5 seconds, returns at most 500 rows and is written to the activity log, so never paste a secret into one. The database must be deployed.

• PostgreSQL and MySQL: one statement starting with SELECT, WITH, EXPLAIN, SHOW, TABLE or VALUES (MySQL also DESCRIBE, DESC), in a read-only transaction. A semicolon may only end it.
• Valkey: one read command, such as GET key, HGETALL key or SCAN 0 COUNT 50.
• MongoDB: a JSON document, {"find": "COLLECTION", "limit": 50} or {"countDocuments": "COLLECTION"}.

Add readers and fail overCopy Anchor Link

PostgreSQL databases have a Replicas tab.

1. Set Read replicas to 0–5. The change is staged and applied without downtime.
2. Read each reader's Streaming or Syncing state and lag. To make a reader the writer, select Promote, then Promote to writer (promoteDatabaseReader). It takes effect at once. The old writer rejoins as a reader, and connections to the writer drop for a few seconds.
3. The Automatic failover switch needs at least one reader. When it is on, a writer unreachable for 30 seconds is replaced by the most caught-up reader. It is on by default once a reader exists.

Turn on point-in-time recoveryCopy Anchor Link

On a PostgreSQL database's Backups tab, turn on Point-in-time recovery. In Turn on point-in-time recovery, choose the Object store, enter an Access key ID and Secret access key, optionally a Prefix (default PROJECT/SLUG/ENVIRONMENT), then select Turn on. Use a key scoped to that prefix only, never the organization's main key. The cluster needs the Barman Cloud Plugin, which the CloudNativePG install adds. In production this step needs admin.

To restore, enter a moment in the UTC field and select Restore to this moment…, then Restore (admin). The console refuses a future moment and, once the archive reports its range, an earlier one than it holds. The restore creates NAME-restored-YYYYMMDD-HHMM with the same version, size, CPU and memory, and deploys it at once; the original is not touched. In this environment the new database keeps the original's password; its other environments start empty. In production the deploy waits for approval. Point services at the new database once you have checked it. The API operations are putDatabasePitr and restoreDatabasePitr.

Back up and restore from a dumpCopy Anchor Link

When the organization has an object store at creation, each environment gets a daily dump, taken between 02:00 and 04:59 UTC, keeping the last 7. Without one, the console warns "has no scheduled backups". Add a store later, then on the Backups tab select Schedule…. Dumps run while the database keeps serving.

To restore PostgreSQL, Valkey, MySQL or MongoDB from a dump:

Restoring needs admin. Progress shows under Restore history. After a restore into a new service, connect your services to it and delete the old one when you no longer need it.

Move to a newer major versionCopy Anchor Link

A database keeps the major version its data was created under. To move to the newest:

1. On the Backups tab, select Back up now on the old database. Read the objectKey of the succeeded backup with GET BASE_URL/api/v1/volumes/VOLUME_ID/backups?environmentId=ENVIRONMENT_ID (listVolumeBackups).
2. Add a new database as above and deploy it.
3. On the new database's Backups tab, select Restore…, From an object key, the same object store and the key. Under Restore into, choose In place, type the new database's name to confirm, then restore. The new database is empty, so nothing is lost.
4. Check the data on the Data tab, connect your services to the new database, then delete the old one.

Install CloudNativePG on a clusterCopy Anchor Link

A newly installed cluster already has it. Without it, deploying a PostgreSQL database is refused with "this cluster doesn't run CloudNativePG yet: install it from the cluster's settings (Install CloudNativePG), then deploy again", and the database's Settings tab shows an Install CloudNativePG button that opens the cluster's settings. An admin installs it from Clusters: open the cluster, then the Settings tab. Under CloudNativePG, select Install CloudNativePG. The console shows an Install command and a One-time token. Run the command on the cluster's first server and paste the token at the NebulaCtrl token: prompt. It installs cert-manager, the Barman Cloud Plugin and the operator, applies this release's custom resource definitions, and is safe to run again with a new token (installClusterCnpg).

Stop or delete a databaseCopy Anchor Link

On the database's Settings tab, Stop in ENVIRONMENT scales every process to zero in that environment and withdraws its domains. The release, variables and volumes stay, and Start in ENVIRONMENT brings back what ran. A PostgreSQL database hibernates its CloudNativePG cluster instead, which keeps its volumes.

Hold Delete service to confirm. Service variables whose whole value is a reference to the database's connection URL (DATABASE_URL, or DATABASE_READ_URL on PostgreSQL), and that no nebula.toml sets, are removed with it. Any other referring variable blocks the delete with a message such as "SLUG is still referenced by KEY on SERVICE in ENVIRONMENT: remove or change those variables first, then delete it". It names up to five referrers, then "and N more".

VerifyCopy Anchor Link

The database shows healthy on the canvas, its Data tab lists the service under Connected services, and SELECT 1 in the Query box returns a row.

Next stepsCopy Anchor Link