PostgreSQL

A PostgreSQL resource is a managed database that Kuppit provisions, backs up and keeps credentials for. Services connect to it through the variables it exposes; you never copy a connection string by hand.

Where a database can live

A database is added to Production or to a custom environment. Preview environments never get one: they are created from pull requests and are meant to be disposable, and copying production data into every pull request is the accident that rule exists to prevent.

Adding a database

On an environment's Overview, choose Add resource, then PostgreSQL. Kuppit asks how the database should be created, and for a name. The default name is database, and the name is how services address it in references, so database is a good choice unless the environment has more than one.

Review the plan and create it. Provisioning takes a few minutes; the resource shows its progress and becomes Ready when it can accept connections. A database that fails to provision can be retried or deleted from its Overview.

New, cloned or shared

When the project already has a database in another environment, there are three ways to create this one:

Either can also be started from the database itself: on the project's Overview, right-click its card and choose Copy to environment…, or drag the card onto another long-lived environment's box, and the same choice opens with that database as the source. See Copying a resource.

A shared database belongs to the environment it was created in. The Overview draws it there, and draws the connection from this environment's services as an edge into that environment's box — in amber when the owner is Production — and this environment's box says beneath its cards that it uses that database. Writes from here change that environment's data. Removing it from this environment does not delete it.

Sizes

A size is the most compute a database may use; it scales down when idle and suspends after a few idle minutes, and the first connection after that takes a moment longer. Storage is not part of the size: it grows with the data you store and is metered as used. Sizes are provisional during the alpha and are set when the database is created.

A database is billed for its compute-unit hours while active and its GB-months of storage while it exists, at the published rates; a suspended database uses no compute.

Variables a database exposes

A database exposes seven variables. They are names only: the values are composed when Kuppit prepares a deployment, from the database's current credentials and address, and are never stored on a service or shown in the dashboard.

PGPASSWORD and DATABASE_URL are secret wherever they end up: a service variable that references one is treated as a secret regardless of what you named it.

Connecting a service

The direct way is a connection: on the project's Overview, right-click the service, choose Connect to…, then the database. Kuppit injects the seven variables above into the service as references, under these names unless you choose others, and the connection owns them from then on.

The other way is one variable at a time. On the service's Variables tab, add a variable and choose Reference instead of typing a value. Select the database and the variable it should resolve to. The service stores the reference, not the value:

DATABASE_URL = ${{ database.DATABASE_URL }}

Then redeploy. Your application reads the resolved value as an ordinary environment variable:

import { Client } from 'pg'

const db = new Client({
    connectionString: process.env.DATABASE_URL
})

References are resolved when Kuppit prepares runtime configuration for a deployment. If a managed database credential changes, a service referencing ${{ database.DATABASE_URL }} does not require you to copy the new value into its variables; the next deployment picks it up.

Either way the result is the same at deploy time: a reference, resolved when the deployment is prepared. The service's Connect tab lists every reference it holds, and the project's Overview draws the connection as an edge between the service and the database.

Deleting a database

Choose Delete database on the database's card on the project's Overview — on a right-click, behind its ellipsis, or on its panel — or on its Settings tab. The same menu offers How to connect, which opens the Connect tab.

A database that other databases were cloned from cannot be deleted while any of those clones exist. Delete the clones first; the dialog names them.

Deleting also removes every connection to the database and every variable that references it, so each connected service loses its connection at its next deployment. Kuppit names those services before you confirm. Usage history is kept for billing, and the Usage page keeps showing the database under the name it had, marked as deleted; nothing else can be recovered.