runlot docs

Every database command in the CLI. A database belongs to your organization and is named; the commands take its name, and default to the database named after the project in the current directory.

runlot pg is now runlot db. For one release runlot pg … stops with the new command; after that it is gone. Databases now belong to your organization: deleting a project keeps its database, which you delete separately.

Every command takes the database's name. Leave the name out and the command uses the database named after the project in the current directory's runlot.json — the one the project reads as env.db. Use --dir <path> to point at a project in another directory.

runlot db shell                 # the database named after this project
runlot db shell reports         # the database named reports

Listing, creating and deleting

Command	Role	What it does
`runlot db list`	viewer	Every database in the organization: its size against the cap, whether it is running or asleep, and which projects bind it under which name. A database no project binds is shown as unbound.
`runlot db create <name>`	member	Creates an empty database. With a project's name it creates that project's `env.db`; any other name creates a database of its own, which needs the Pro plan.
`runlot db delete <name>`	admin	Deletes the database and its data. Refused while a project binds it; the error names each project.
`runlot db delete <name> --unbind-all`	admin	Removes every binding first, then deletes. The projects that bound it get `DatabaseNotAttached` until their `runlot.json` drops the entry and they deploy again.

Deleting a database asks you to type its name. A database that no app shares a name with is deleted without a final backup, so run runlot db export first if you want a copy.

Working with the data

Command	Role	What it does
`runlot db connect [name]`	member	Prints the connection details, password included.
`runlot db shell [name] [-- …]`	member	Opens `psql`. Arguments after `--` go to `psql`. See psql.
`runlot db execute [name]`	member	Runs SQL: `-c "<sql>"` or `-f <file>`.
`runlot db export [name]`	member	Writes a diagnostic dump. It is not a backup and cannot be restored.
`runlot db migrate [name] [--from <dir>]`	member	Applies `NNNN_*.sql` files in order, from `./migrations` by default. It first lists the projects that bind the database. See Migrations.
`runlot db forward [name]`	member	Forwards a local port to the database over your login session (`--port 15432`, `--listen 127.0.0.1`, Ctrl-C to stop).

Backups

Command	Role	What it does
`runlot db backups [name]`	viewer	Lists the backups (`--json` for raw output).
`runlot db restore <backup> [name]`	admin	Restores to a backup, a commit or a time. See Backup and restore.
`runlot db abort <opId> [name]`	admin	Aborts a running restore or delete.

Credentials for machines

Command	Role	What it does
`runlot db token [name]`	member	Issues short-lived credentials (`--ttl`, `--json`).
`runlot db token list [name]`	member	Lists the credentials you issued.
`runlot db token revoke <user> [name]`	member	Revokes credentials.

See Database tokens.

The old commands

Before	Now
`runlot pg on`	`runlot db create <project>`
`runlot pg generations`	`runlot db backups`
`runlot pg delete`	`runlot db delete <name>`
`runlot pg connect`, `shell`, `execute`, `export`, `migrate`, `restore`, `abort`, `token`	the same verb under `runlot db`
`runlot port-forward`	`runlot db forward`

runlot.json files keep working unchanged. A project's env.db is still the database named after the project.

runlot db