Reaching a database
A service does not reach its database over the public network. When a service references a database, Kuppit attaches the database to the service's revision, and the connection runs over a socket the infrastructure mounts inside the container. The application sees ordinary PostgreSQL connection variables; only their values are shaped by the socket.
What the variables contain
| Variable | Value |
|---|---|
PGHOST | A directory path such as /cloudsql/<instance>. PostgreSQL clients treat a host beginning with / as a Unix socket directory. |
PGPORT | 5432. For a socket it names the socket file, .s.PGSQL.5432, rather than a TCP port. |
PGUSER, PGPASSWORD, PGDATABASE | The credentials Kuppit created with the database. |
DATABASE_URL | postgresql://<user>:<password>@localhost/<database>?host=/cloudsql/<instance>&port=5432. The localhost is a placeholder the host parameter overrides. |
Every mainstream client understands this shape: pg, Prisma, Drizzle, psycopg, database/sql. Pass DATABASE_URL straight through, or pass the five parts; do not rebuild the string by hand from a template that assumes a hostname.
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 never public. The database accepts encrypted connections only, and no network is authorised to reach it. The socket is the one way in, and it exists only inside a revision that references the database.
- 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.
- Local development is different. Your machine has no socket. 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. There is no public address to point a desktop client at. The service's Connect tab describes the variables; a migration or an admin task runs from a service in the environment.
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.