Reaching a database
A service reaches its database over an encrypted, verified TLS connection. When a service references a database — by a connection made on the project's Overview, or by a reference written on its Variables tab — Kuppit composes ordinary PostgreSQL connection variables for the revision, and the application connects with them as it would to any PostgreSQL server.
What the variables contain
| Variable | Value |
|---|---|
PGHOST | The database's hostname. |
PGPORT | 5432. |
PGUSER, PGPASSWORD, PGDATABASE | The credentials Kuppit created with the database. |
PGSSLMODE | verify-full: the connection is encrypted and the server's certificate is verified. |
DATABASE_URL | postgresql://<user>:<password>@<host>:5432/<database>?sslmode=verify-full. |
Every mainstream client understands this shape: pg, Prisma, Drizzle, psycopg, database/sql. Pass DATABASE_URL straight through, or pass the parts; if you assemble a connection yourself from the parts, keep PGSSLMODE — a client configured to skip verification is connecting to something it has not checked is your database.
The values are composed when Kuppit prepares a deployment, from the database's state at that moment. They are never stored on the service and never shown in the dashboard.
What it means for you
- Encrypted, and verified. The database accepts TLS connections only, and the variables ask the client to verify the server. Nothing in the values weakens that.
- Same environment only. A reference can only target a database beside the service in its environment. A database in another environment is, to a service, indistinguishable from one that does not exist. The exception is a database the environment shares from another, which is bound into this environment on purpose.
- Idle databases wake on connection. A database that has been idle for a few minutes suspends its compute; the first connection afterwards takes a moment longer while it wakes. A client with a sensible connection timeout handles this without configuration.
- Local development is different. Use a local PostgreSQL, or a connection string of your own, in your local
.env; the service's variables are Kuppit's alone. - No client from outside. Kuppit does not hand out the credentials for a desktop client. The service's Connect tab describes the variables; a migration or an admin task runs from a service in the environment.
Databases created before TLS connections were the norm connect over a socket the infrastructure mounts in the revision; their PGHOST is a path such as /cloudsql/<instance>, PGSSLMODE is disable, and DATABASE_URL carries the socket as a host parameter. Pass the variables through as they are and both shapes work.
When attachment fails
A reference is resolved when a deployment is prepared. If the database exists but its address is not known yet, or the service and the database sit on infrastructure that cannot be connected, the deployment fails before anything is built and says why. Reference failures has the messages that are yours to fix; failures that are Kuppit's has the rest.