Skip to main content
An environment on Reliant hosting can have a Postgres database that the platform provisions and operates for you. Each database is its own server in your organization’s namespace for that environment, so no other customer shares it, and staging never receives a credential for prod’s data. This page covers how you declare one, what its backups do and don’t cover, how to read its data safely, and what happens to it when you delete the environment.

Declare the database

A database is a forge.ManagedDatabase in the environment’s KCL (deploy/kcl/<env>/main.k), bound to hosted runtime. A workload reaches it through forge.DatabaseRef:
forge project new scaffolds this for a service project, so you usually edit the declaration rather than write it. The spec accepts 1 to 3 instances and 1 to 500 storageGiB (the default is 10). The name must be a lowercase DNS label of at most 40 characters, and it can’t be api, which is the name of the hosted service workload. The platform allocates the namespace, so don’t set namespace on a hosted database. Each environment declares its own database, so staging and prod never share data. A database is created with the first deploy of an environment that declares it, and billed like any hosted workload: until hosting billing is active the deploy is queued, and nothing is created.

How credentials reach your app

forge.DatabaseRef makes the platform fill DATABASE_URL in the workload at deploy time. You never copy a connection string into a secret. The owner credential is generated inside the cluster and published only to your workloads; the control plane holds no copy of it. The one credential the control plane reads is the read-only role’s (forge_ro), fetched from your environment’s cluster for each audited forge db query and not stored. The database is also fenced off from everything else. It starts default-deny, accepts connections only from your own workloads, and has no internet egress other than its backup storage and the cluster API. That is why you can’t reach it from your laptop with a connection string: use forge db query instead.

Migrations run in the deploy

Hosted migrations run as a job before the rollout (before = [fw.BEFORE_ALL]), inside the platform, because the database is unreachable from outside. forge db migrate up --dsn can’t reach it either. A migration can’t wedge a deploy by waiting forever on a lock: each statement runs with a lock_timeout of 5 seconds, retried five times with backoff, and a statement_timeout of 30 minutes. A file can override either limit with -- forge:lock-timeout or -- forge:statement-timeout. CREATE INDEX CONCURRENTLY cleans up an index left invalid by an earlier failed attempt. Before you push, forge lint --migration-safety flags migrations that are risky on a live table (migration rules), and forge db analyze runs pending migrations on a disposable Postgres and reports the locks, rewrites and scans each statement caused.

Backups and point-in-time restore

A hosted database is built for continuous WAL archiving plus a daily base backup, written to object storage. On Reliant’s production platform, backups are kept for 7 days, so you can restore to any moment in that window. Each database writes its archive with its own workload identity, which can reach only that database’s own stream. No shared backup credential exists in your namespace. Three conditions limit that promise:
  • The platform’s backup storage has to be ready. Backups are switched on by the platform once its backup bucket exists. Until then a database reports that its backups are not active, and has none. Turning them on restarts a single-instance database once.
  • Claimable databases aren’t backed up. A deploy without an account has one Postgres with no backups. Only databases in an account’s environments are backed up.
  • The window is 7 days. You can’t restore to a moment older than that.

How backup health is tracked

The platform tracks each database’s backup state as three separate facts, because each can fail on its own: when the last base backup finished, whether WAL is reaching storage, and the oldest point you can still restore to, along with the last archiving or backup error verbatim. A database whose backup storage isn’t ready yet reports that its backups are not active. A built-in alert pages when a database’s backups are on and failing, because a database whose archiving has stopped keeps serving traffic normally while its recovery window shrinks. There is no forge command yet that prints a database’s backup status, so the alert is how you find out. If the status reports no backups yet, or an oldest restorable point that is later than the incident you care about, treat that incident as not recoverable from a backup.

Restore is a declaration

There is no restore button or command. To restore, you declare a new ManagedDatabase whose spec names the database to read and, optionally, the moment to stop at:
Then run forge env deploy <env>. The platform creates the new database from the source’s base backup and replays the archive up to pointInTime. A few rules follow from how it works:
  • A restore applies once, when the database is created, and never overwrites the source. A mistaken restore can’t destroy the original.
  • The source must be a database in the same environment. You can’t restore prod’s backups into staging.
  • pointInTime must be an RFC 3339 timestamp, and a restore with no sourceDatabase is refused.
  • The restored database is a separate database with its own archive stream. Check its data with forge db query --database notes-restored, then point a workload at it with forge.DatabaseRef {name = "notes-restored"}.
The platform’s restore is exercised by an automated drill that takes a backup, destroys the database and its volumes, restores to a timestamp, and asserts that rows from before it came back and rows from after it did not.

Read the data safely

forge db query <env> "<sql>" runs one statement against an environment’s database and prints the rows. It is the supported way to look at hosted data, and it is built so that an agent or a person can use it on prod:
  • Read only. Every statement runs in a READ ONLY transaction with a statement timeout and a row cap (200 rows by default, 10,000 at most), as one statement that is rolled back. Writes, DDL and a second statement are refused. Data fixes belong in migrations or application code.
  • Secret columns stay hidden. The query runs as a read-only role (forge_ro) that can’t read columns marked forge:secret, however the query asks (select *, a function over the column or row_to_json). A credential-shaped column, such as a token, password or key, must be marked forge:secret or forge:readable with a reason before lint will pass (forge lint --db-grants).
  • A named reason and an audit record. On a real environment you pass --confirm-env <env> (the name again) and --reason. A hosted query needs the organization’s db:query grant, which owners and admins hold, and is recorded in the control plane’s audit log and activity feed. It is limited to one query at a time per person and 30 a minute.
  • A policy per environment. data_access = forge.DataAccess {db_query = "audited"} in the environment’s KCL sets who may query: open, audited (a person, with confirmation and a reason) or deny (nobody).
A non-zero exit of 2 means forge could not look, not that there were no rows. forge agent skill load db/query has the transports, the JSON output and every exit code.

Delete an environment, keep the data

Deleting a hosted environment destroys its managed databases with it. To keep the data, add --keep-data:
A kept database keeps running and is billed as storage. It is not reattached by a later deploy. List and remove retained databases with:
Nothing else ever deletes retained data, so a kept database stays, and keeps billing, until you purge it. forge app teardown --keep-data does the same for every environment of the app.

What it doesn’t do

  • No automatic scaling of the database. You set instances and storageGiB in the declaration.
  • One region. Hosted services and managed databases run in GCP us-central1, with no region choice. To run elsewhere, bind a database to a cluster you operate with forge.OnCluster.
  • No restore command. Restore is the declaration above, and a restore reads only same-environment backups.

Bring your own database

You don’t have to use the managed one. Keep your own Postgres and set its connection string as a secret with forge env secret set --env <env> DATABASE_URL (see Secrets); to let forge db query read a database forge doesn’t run, such as Cloud SQL or RDS, declare it as a forge.ExternalDatabase in the environment’s external_databases. forge renders nothing for it; the declaration only gives forge db query a route, under the same read-only and audit rules. Backups of a database you bring are yours to manage. A workload on Reliant hosting reaches the internet only over TCP 80 and 443, so it cannot connect to a Postgres server outside hosting on 5432; bringing your own database works for workloads bound to a cluster you operate.