SetCloud
✦ Ask AI Get started

Connecting to your database

Your app never asks you to paste a connection string — it already has one. This page covers where DATABASE_URL comes from, how pooling works, and why database clients must run inside the linked SetCloud deployment.

The DATABASE_URL variable

The moment a database is attached to a project, its connection string is stored as a deployment secret. Adding it from Databases starts the deployment that injects it as DATABASE_URL. It is generated for you, never typed in, never committed to your repo, and never returned by the Databases API.

Connecting from app code

Read DATABASE_URL the way you’d read any environment variable and hand it to your Postgres client of choice:

import pg from 'pg';

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
const { rows } = await pool.query('SELECT now()');

The connection requires TLS — DATABASE_URL already carries the flag your client needs, so no extra configuration is required.

Connection pooling

Every connection your app opens against DATABASE_URL passes through a pooling layer SetCloud maintains in front of the database. A traffic spike or a burst of cold starts opening many connections at once doesn’t translate into that many new connections hitting the database directly — the pool absorbs it. You don’t provision, size, or maintain this layer yourself; it comes with the database.

Connecting an external client

The managed pool is on private shared networking and is not exposed for direct connections from a laptop or public GUI client. Run migrations and administrative jobs from the linked SetCloud deployment. Do not print DATABASE_URL or add a route that returns it; both approaches turn a deployment-scoped credential into a reusable leak.

Next