wehub-resource-sync
194 lines
7.2 KiB
Markdown
194 lines
7.2 KiB
Markdown
# Connection Methods
|
|
|
|
Guide to selecting the optimal connection method for your Neon Postgres database based on deployment platform and runtime environment.
|
|
|
|
For official documentation:
|
|
|
|
```bash
|
|
curl -H "Accept: text/markdown" https://neon.tech/docs/connect/choose-connection
|
|
```
|
|
|
|
## Decision Tree
|
|
|
|
Follow this flow to determine the right connection approach:
|
|
|
|
### 1. What Language Are You Using?
|
|
|
|
**Not TypeScript/JavaScript** → Use **TCP with connection pooling** from a secure server.
|
|
|
|
For non-TypeScript languages, connect from a secure backend server using your language's native Postgres driver with connection pooling enabled.
|
|
|
|
| Language/Framework | Documentation |
|
|
| ------------------- | ------------------------------------------- |
|
|
| Django (Python) | https://neon.tech/docs/guides/django |
|
|
| SQLAlchemy (Python) | https://neon.tech/docs/guides/sqlalchemy |
|
|
| Elixir Ecto | https://neon.tech/docs/guides/elixir-ecto |
|
|
| Laravel (PHP) | https://neon.tech/docs/guides/laravel |
|
|
| Ruby on Rails | https://neon.tech/docs/guides/ruby-on-rails |
|
|
| Go | https://neon.tech/docs/guides/go |
|
|
| Rust | https://neon.tech/docs/guides/rust |
|
|
| Java | https://neon.tech/docs/guides/java |
|
|
|
|
**TypeScript/JavaScript** → Continue to step 2.
|
|
|
|
---
|
|
|
|
### 2. Client-Side App Without Backend?
|
|
|
|
**Yes** → Use **Neon Data API** via `@neondatabase/neon-js`
|
|
|
|
This is the only option for client-side apps since browsers cannot make direct TCP connections to Postgres. See `neon-js.md` for setup.
|
|
|
|
```bash
|
|
curl -H "Accept: text/markdown" https://neon.tech/docs/reference/javascript-sdk
|
|
```
|
|
|
|
**No** → Continue to step 3.
|
|
|
|
---
|
|
|
|
### 3. Long-Running Server? (Railway, Render, traditional VPS)
|
|
|
|
**Yes** → Use **TCP with connection pooling** via `node-postgres`, `postgres.js`, or `bun:pg`
|
|
|
|
Long-running servers maintain persistent connections, so standard TCP drivers with pooling are optimal.
|
|
|
|
**No** → Continue to step 4.
|
|
|
|
---
|
|
|
|
### 4. Edge Environment Without TCP Support?
|
|
|
|
Some edge runtimes don't support TCP connections. Rarely the case anymore.
|
|
|
|
**Yes** → Continue to step 5 to check transaction requirements.
|
|
|
|
**No** → Continue to step 6 to check pooling support.
|
|
|
|
---
|
|
|
|
### 5. Does Your App Use SQL Transactions?
|
|
|
|
**Yes** → Use **WebSocket transport** via `@neondatabase/serverless` with `Pool`
|
|
|
|
WebSocket maintains connection state needed for transactions. See `neon-serverless.md` for setup.
|
|
|
|
**No** → Use **HTTP transport** via `@neondatabase/serverless`
|
|
|
|
HTTP is faster for single queries (~3 roundtrips vs ~8 for TCP). See `neon-serverless.md` for setup.
|
|
|
|
```bash
|
|
curl -H "Accept: text/markdown" https://neon.tech/docs/serverless/serverless-driver
|
|
```
|
|
|
|
---
|
|
|
|
### 6. Serverless Environment With Connection Pooling Support?
|
|
|
|
**Vercel (Fluid Compute)** → Use **TCP with `@vercel/functions`**
|
|
|
|
Vercel's Fluid compute supports connection pooling. Use `attachDatabasePool` for optimal connection management.
|
|
|
|
```bash
|
|
curl -H "Accept: text/markdown" https://neon.tech/docs/guides/vercel-connection-methods
|
|
```
|
|
|
|
**Cloudflare (with Hyperdrive)** → Use **TCP via Hyperdrive**
|
|
|
|
Cloudflare Hyperdrive provides connection pooling for Workers. Use `node-postgres` or any native TCP driver.
|
|
|
|
See https://neon.tech/docs/guides/cloudflare-hyperdrive for more on connecting with Cloudflare Workers and Hyperdrive.
|
|
|
|
**No pooling support (Netlify, Deno Deploy)** → Use `@neondatabase/serverless`
|
|
|
|
Fall back to the decision in step 5 based on transaction requirements.
|
|
|
|
---
|
|
|
|
## Quick Reference Table
|
|
|
|
| Platform | TCP Support | Pooling | Recommended Driver |
|
|
| ----------------------- | ----------- | ------------------- | -------------------------- |
|
|
| Vercel (Fluid) | Yes | `@vercel/functions` | `pg` (node-postgres) |
|
|
| Cloudflare (Hyperdrive) | Yes | Hyperdrive | `pg` (node-postgres) |
|
|
| Cloudflare Workers | No | No | `@neondatabase/serverless` |
|
|
| Netlify Functions | No | No | `@neondatabase/serverless` |
|
|
| Deno Deploy | No | No | `@neondatabase/serverless` |
|
|
| Railway / Render | Yes | Built-in | `pg` (node-postgres) |
|
|
| Client-side (browser) | No | N/A | `@neondatabase/neon-js` |
|
|
|
|
---
|
|
|
|
## ORM Support
|
|
|
|
Popular TypeScript/JavaScript ORMs all work with Neon:
|
|
|
|
| ORM | Drivers Supported | Documentation |
|
|
| ------- | ----------------------------------------------- | ------------------------------------- |
|
|
| Drizzle | `pg`, `postgres.js`, `@neondatabase/serverless` | https://neon.tech/docs/guides/drizzle |
|
|
| Kysely | `pg`, `postgres.js`, `@neondatabase/serverless` | https://neon.tech/docs/guides/kysely |
|
|
| Prisma | `pg`, `@neondatabase/serverless` | https://neon.tech/docs/guides/prisma |
|
|
| TypeORM | `pg` | https://neon.tech/docs/guides/typeorm |
|
|
|
|
All ORMs support both TCP drivers and Neon's serverless driver depending on your platform.
|
|
|
|
For Drizzle ORM integration with Neon, see `neon-drizzle.md`.
|
|
|
|
---
|
|
|
|
## Vercel Fluid + Drizzle Example
|
|
|
|
Complete database client setup for Vercel with Drizzle ORM and connection pooling. See `neon-drizzle.md` for more examples.
|
|
|
|
```typescript
|
|
// src/lib/db/client.ts
|
|
import { attachDatabasePool } from "@vercel/functions";
|
|
import { drizzle } from "drizzle-orm/node-postgres";
|
|
import { Pool } from "pg";
|
|
|
|
import * as schema from "./schema";
|
|
|
|
const pool = new Pool({
|
|
connectionString: process.env.DATABASE_URL,
|
|
});
|
|
attachDatabasePool(pool);
|
|
|
|
export const db = drizzle({ client: pool, schema });
|
|
```
|
|
|
|
**Why `attachDatabasePool`?**
|
|
|
|
- First request establishes the TCP connection (~8 roundtrips)
|
|
- Subsequent requests reuse the connection instantly
|
|
- Ensures idle connections close gracefully before function suspension
|
|
- Prevents connection leaks in serverless environments
|
|
|
|
---
|
|
|
|
## Gathering Requirements
|
|
|
|
When helping a user choose their connection method, gather this information:
|
|
|
|
1. **Deployment platform**: Where will the app run? (Vercel, Cloudflare, Netlify, Railway, browser, etc.)
|
|
2. **Runtime type**: Serverless functions, edge functions, or long-running server?
|
|
3. **Transaction requirements**: Does the app need SQL transactions?
|
|
4. **ORM preference**: Using Drizzle, Kysely, Prisma, or raw SQL?
|
|
|
|
Then provide:
|
|
|
|
- The recommended driver/package
|
|
- A working code example for their setup
|
|
- The correct npm install command
|
|
|
|
---
|
|
|
|
## Documentation Resources
|
|
|
|
| Topic | URL |
|
|
| -------------------------- | ------------------------------------------------------- |
|
|
| Choosing Connection Method | https://neon.tech/docs/connect/choose-connection |
|
|
| Serverless Driver | https://neon.tech/docs/serverless/serverless-driver |
|
|
| JavaScript SDK | https://neon.tech/docs/reference/javascript-sdk |
|
|
| Connection Pooling | https://neon.tech/docs/connect/connection-pooling |
|
|
| Vercel Connection Methods | https://neon.tech/docs/guides/vercel-connection-methods |
|