Choosing your connection method

Your connection method depends on where your code runs. Use the table below for a quick lookup, or read the scenario sections for detailed guidance.

Quick reference by environment

Each scenario is described in detail further down the page.

Find your scenario

Not using JavaScript or TypeScript?

Use a standard TCP-based Postgres driver with a pooled connection. Connect from a secure backend server using your language's native driver.

For the full list, see Language quickstarts.

Running on a long-lived server (JS/TS)?

If you deploy a JavaScript or TypeScript app to Railway, Render, a VPS, Docker, or any self-hosted environment with persistent processes, use a standard TCP driver with connection pooling. Your server can maintain a connection pool across requests, making TCP the fastest and most efficient option.

Recommended drivers: pg (node-postgres), postgres.js, or Bun.SQL.

Deploying to Vercel or Cloudflare with platform pooling?

These platforms provide their own connection pooling, which makes standard TCP the best choice.

Vercel (Fluid compute): Use pg (node-postgres) with @vercel/functions. Vercel Fluid keeps functions warm long enough to reuse TCP connections, so you skip the connection setup cost on subsequent requests. See the Vercel connection methods guide for details.

Cloudflare (Hyperdrive): Use pg (node-postgres) with Hyperdrive, which provides connection pooling for Workers. See the Cloudflare Hyperdrive guide for setup.

Deploying to another serverless or edge platform?

For platforms like Netlify Functions, Deno Deploy, or Cloudflare Workers (without Hyperdrive), use the Neon serverless driver (@neondatabase/serverless). It connects over HTTP or WebSockets instead of TCP, reducing connection setup latency.

Choose your transport based on your query pattern: use HTTP for single queries and non-interactive transactions, or WebSocket for interactive transactions and node-postgres compatibility. See HTTP vs. WebSocket for details.

Building a client-side app without a backend?

Use the Neon Data API via @neondatabase/neon-js. Browsers cannot open TCP connections to Postgres, so the Data API provides a secure HTTP interface with Row-Level Security support.

See the JavaScript SDK reference for full documentation.

Understanding the options

Pooled vs. direct connections

A pooled connection routes traffic through PgBouncer, which manages a pool of reusable Postgres connections. Use pooled connections by default. They handle up to 10,000 concurrent client connections and work well for serverless apps and high-concurrency workloads.

A direct connection connects straight to Postgres without PgBouncer. Use direct connections for operations that require stable, long-lived connections or features PgBouncer does not support, such as:

• Schema migrations (Prisma Migrate, Drizzle Kit, django-admin migrate)
• CREATE INDEX CONCURRENTLY
• LISTEN / NOTIFY
• Temporary tables or prepared statements across multiple queries

Direct connections are limited by max_connections, which ranges from about 100 to 4,000 depending on your compute size.

You select pooled or direct by choosing the right connection string. Pooled strings include -pooler in the hostname:

# Pooled
postgresql://user:pass@ep-cool-rain-123456-pooler.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require

# Direct
postgresql://user:pass@ep-cool-rain-123456.us-east-2.aws.neon.tech/neondb?sslmode=require&channel_binding=require

See Connection pooling for details.

HTTP vs. WebSocket (serverless driver)

The Neon serverless driver supports two transports:

• HTTP uses fetch requests. It is faster for single queries (~3 round trips vs. ~8 for TCP) and supports non-interactive transactions. Choose HTTP when your queries are independent, one-shot operations.
• WebSocket maintains a persistent connection within a request. It supports interactive transactions and is compatible with the node-postgres API (Pool, Client). Choose WebSocket when you need multi-step transactions or pg compatibility.

Data API

The Data API provides a REST interface to your database over HTTP. It works in browsers, edge runtimes, and anywhere you can make HTTP requests. It validates JWTs from any authentication provider and enforces PostgreSQL Row-Level Security, making it suitable for client-side apps that query the database directly.

ORM compatibility

Popular JavaScript and TypeScript ORMs work with Neon across all connection methods. For non-JS/TS ORMs (Django, SQLAlchemy, ActiveRecord, Ecto), use your language's native Postgres driver with a pooled connection.

Choose the driver based on your platform (see the scenarios above), then configure your ORM to use it.

Common pitfalls