PostgreSQL

A PostgreSQL resource is a managed database that Kuppit provisions, backs up and keeps credentials for. Services connect to it by referencing 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:

A shared database belongs to the environment it was created in. This environment's Overview marks it Shared, and writes from here change that environment's data. Removing it from this environment does not delete it.

Sizes

Sizes are provisional during the alpha and are set when the database is created.

Variables a database exposes

A database exposes six 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

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.

The service's Connect tab lists every reference it holds, and the environment's Overview draws the connection as an edge from the database to the service.

Deleting a database

Deleting also removes every variable that references the database, so each connected service loses its connection at its next deployment. Kuppit names those services before you confirm. Usage history is kept for billing; nothing else can be recovered.