Declare the database
A database is aforge.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 newManagedDatabase whose spec names the database to read and, optionally, the moment to stop at:
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.
pointInTimemust be an RFC 3339 timestamp, and a restore with nosourceDatabaseis 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 withforge.DatabaseRef {name = "notes-restored"}.
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 ONLYtransaction 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 markedforge:secret, however the query asks (select *, a function over the column orrow_to_json). A credential-shaped column, such as a token, password or key, must be markedforge:secretorforge:readablewith 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’sdb:querygrant, 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) ordeny(nobody).
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:
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
instancesandstorageGiBin 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 withforge.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 withforge 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.