Database migrations
Run schema migrations without routing through PgBouncer.
Neon · Const
Direct endpoint
DATABASE_URL_UNPOOLED is Neon’s direct PostgreSQL connection string. Use it for migrations and other operations that require a non-pooled connection.
How it works
Neon exposes the direct database connection string through the DATABASE_URL_UNPOOLED environment variable. Use it when a workload needs a non-pooled Postgres connection, such as migrations, LISTEN/NOTIFY, or transactions involving multiple round trips.
Syntax
DATABASE_URL_UNPOOLED=<direct PostgreSQL connection string>Returns
A direct PostgreSQL connection string supplied through the DATABASE_URL_UNPOOLED environment variable.
Key points
DATABASE_URL_UNPOOLEDcontains Neon’s direct, non-pooled PostgreSQL connection string.- The variable is intended for migrations, PostgreSQL
LISTEN/NOTIFY, and transactions that require multiple round trips. - Neon Functions can provide this value automatically as an injected environment variable.
Example: Read the direct connection string
const connectionString = process.env.DATABASE_URL_UNPOOLED;
if (!connectionString) throw new Error("DATABASE_URL_UNPOOLED is required");
console.log(connectionString);Reads Neon’s injected direct connection string, which can be passed to a Postgres driver or migration tool.
When to use it
Session-dependent features
Use PostgreSQL session features such as LISTEN/NOTIFY.
Multi-round-trip transactions
Execute transactions that require several database round trips.
Interview questions
QWhat does DATABASE_URL_UNPOOLED represent?
DATABASE_URL_UNPOOLED is Neon’s injected environment variable for the direct Postgres connection string. It is intended for operations that need a non-pooled connection, including migrations and session-oriented features.
Follow-up: When should the pooled variable be preferred? Use the pooled connection for ordinary application traffic when supporting a higher number of concurrent connections is the priority.
QWhy use the direct connection for migrations?
Use the direct connection for migrations because pooled connections can cause migration errors. The direct connection avoids routing migration traffic through the connection pool.
Follow-up: What other operations are listed for the direct variable? Neon also names LISTEN/NOTIFY and multi-round-trip transactions.
QHow is this direct connection different from Neon’s Data API?
The direct connection is not the same as a Data API endpoint: it is a PostgreSQL connection string exposed as an environment variable. Code should read it and pass it to a PostgreSQL driver or compatible tool.
Follow-up: What protocol does the Data API use instead? It is accessed through HTTP and secured with JWT authentication and Row-Level Security.
Related
DATABASE_URLDATABASE_URL_POOLEDDATABASE_URL_UNPOOLEDLISTEN/NOTIFY