Related docs
Repository
How to use
You can use these rules in two ways:
Option 1: Copy from this page
Copy the rules below and save them to
.cursor/rules/neon-auth.mdc
in your project.Option 2: Clone from repository
If you prefer, you can clone or download the rules directly from our AI Rules repository.
Once added to your project, AI tools will automatically use these rules when working with Neon Auth code. You can also reference them explicitly in prompts.
Rules
---
description: Use these rules to query your Neon database using the Neon Serverless driver
globs: *.tsx, *.ts
alwaysApply: false
---
# Neon Serverless Guidelines
## Overview
This guide provides specific patterns and best practices for connecting to Neon databases in serverless environments. Follow these guidelines to ensure efficient database connections, proper query handling, and optimal performance in functions with ephemeral runtimes.
## Installation
Install the Neon Serverless PostgreSQL driver with the correct package name:
```bash
npm install @neondatabase/serverless
```
```bash
bunx jsr add @neon/serverless
```
For projects that depend on pg but want to use Neon:
```json
"dependencies": {
"pg": "npm:@neondatabase/serverless@^0.10.4"
},
"overrides": {
"pg": "npm:@neondatabase/serverless@^0.10.4"
}
```
Avoid incorrect package names like `neon-serverless` or `pg-neon`.
## Connection String
Use environment variables for database connection strings:
```javascript
import { neon } from '@neondatabase/serverless';
const sql = neon(process.env.DATABASE_URL);
```
Never hardcode credentials:
```javascript
// Don't do this
const sql = neon('postgres://username:password@host.neon.tech/neondb');
```
## Parameter Interpolation
Use template literals with the SQL tag for safe parameter interpolation:
```javascript
const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`;
```
Don't concatenate strings directly (SQL injection risk):
```javascript
// Don't do this
const [post] = await sql('SELECT * FROM posts WHERE id = ' + postId);
```
## WebSocket Environments
Configure WebSocket support for Node.js v21 and earlier:
```javascript
import { Pool, neonConfig } from '@neondatabase/serverless';
import ws from 'ws';
// Configure WebSocket support for Node.js
neonConfig.webSocketConstructor = ws;
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
```
## Serverless Lifecycle Management
In serverless environments, create, use, and close connections within a single request handler:
```javascript
export default async (req, ctx) => {
// Create pool inside request handler
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
try {
const { rows } = await pool.query('SELECT * FROM users');
return new Response(JSON.stringify(rows));
} finally {
// Close connection before response completes
ctx.waitUntil(pool.end());
}
}
```
Avoid creating connections outside request handlers as they won't be properly closed.
## Query Functions
Choose the appropriate query function based on your needs:
```javascript
// For simple one-shot queries (uses fetch, fastest)
const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`;
// For multiple queries in a single transaction
const [posts, tags] = await sql.transaction([
sql`SELECT * FROM posts LIMIT 10`,
sql`SELECT * FROM tags`
]);
// For session/transaction support or compatibility with libraries
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const client = await pool.connect();
```
Use `neon()` for simple queries rather than `Pool` when possible, and use `transaction()` for multiple related queries.
## Transactions
Use proper transaction handling with error management:
```javascript
// Using transaction() function for simple cases
const [result1, result2] = await sql.transaction([
sql`INSERT INTO users(name) VALUES(${name}) RETURNING id`,
sql`INSERT INTO profiles(user_id, bio) VALUES(${userId}, ${bio})`
]);
// Using Client for interactive transactions
const client = await pool.connect();
try {
await client.query('BEGIN');
const { rows: [{ id }] } = await client.query(
'INSERT INTO users(name) VALUES($1) RETURNING id',
[name]
);
await client.query(
'INSERT INTO profiles(user_id, bio) VALUES($1, $2)',
[id, bio]
);
await client.query('COMMIT');
} catch (err) {
await client.query('ROLLBACK');
throw err;
} finally {
client.release();
}
```
Always include proper error handling and rollback mechanisms.
## Environment-Specific Optimizations
Apply environment-specific optimizations for best performance:
```javascript
// For Vercel Edge Functions, specify nearest region
export const config = {
runtime: 'edge',
regions: ['iad1'], // Region nearest to your Neon DB
};
// For Cloudflare Workers, consider using Hyperdrive instead
// https://neon.tech/blog/hyperdrive-neon-faq
```
## Error Handling
Implement proper error handling for database operations:
```javascript
// Pool error handling
const pool = new Pool({ connectionString: process.env.DATABASE_URL });
pool.on('error', (err) => {
console.error('Unexpected error on idle client', err);
process.exit(-1);
});
// Query error handling
try {
const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`;
if (!post) {
return new Response('Not found', { status: 404 });
}
} catch (err) {
console.error('Database query failed:', err);
return new Response('Server error', { status: 500 });
}
```
## Library Integration
Properly integrate with query builders and ORM libraries:
```javascript
// Kysely integration
import { Pool } from '@neondatabase/serverless';
import { Kysely, PostgresDialect } from 'kysely';
const dialect = new PostgresDialect({
pool: new Pool({ connectionString: process.env.DATABASE_URL })
});
const db = new Kysely({
dialect,
// schema definitions...
});
```
Don't attempt to use the `neon()` function directly with ORMs that expect a Pool interface.