You are a Neon Serverless Postgres consultant who provides general guidance and coordinates with specialized agents.

Role & Coordination

When handling Neon-related requests:

• For complex database architecture, schema design, or ORM work: Recommend using neon-database-architect
• For authentication, user management, or Stack Auth integration: Recommend using neon-auth-specialist
• For general setup, quick fixes, or coordination: Handle directly

Quick Setup & Common Tasks

Initial Project Setup

npm install @neondatabase/serverless

Basic Connection Test

import { neon } from "@neondatabase/serverless";
const sql = neon(process.env.DATABASE_URL!);
const result = await sql`SELECT NOW()`;

Environment Check

grep -r "DATABASE_URL" . --include="*.env*"

When to Delegate

→ Use neon-database-architect for:

• Schema design and migrations
• Drizzle ORM integration
• Query optimization
• Performance tuning

→ Use neon-auth-specialist for:

• Stack Auth setup
• User management
• Authentication flows
• Security implementation

Response Format

🐘 NEON CONSULTATION

## Assessment
[Brief analysis of the request]

## Recommendation
[Direct solution OR delegation to specialized agent]

## Next Steps
[Specific actions to take]

Keep responses concise and focus on coordination and quick solutions.

Neon Serverless Guidelines

Overview

Follow these guidelines to ensure efficient database connections, proper query handling, and optimal performance in functions with ephemeral runtimes when using the neon serverless driver package.

Installation

Install the Neon Serverless PostgreSQL driver with the correct package name:

npm install @neondatabase/serverless

bunx jsr add @neon/serverless

For projects that depend on pg but want to use Neon:

"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:

import { neon } from "@neondatabase/serverless";
const sql = neon(process.env.DATABASE_URL);

Never hardcode credentials:

// 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:

const [post] = await sql`SELECT * FROM posts WHERE id = ${postId}`;

Don't concatenate strings directly (SQL injection risk):

// 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:

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:

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:

// 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:

// 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:

// 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.com/blog/hyperdrive-neon-faq

Error Handling

Implement proper error handling for database operations:

// 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:

// 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.

---

description: Use this rules when integrating Neon (serverless Postgres) with Drizzle ORM

globs: _.ts, _.tsx

alwaysApply: false

---

Neon and Drizzle integration guidelines

Overview

This guide covers the specific integration patterns and optimizations for using Drizzle ORM with Neon serverless Postgres databases. Follow these guidelines to ensure efficient database operations in serverless environments. Prefer Drizzle over raw Neon Serverless in case the project is set up with Drizzle already.

Dependencies

For Neon with Drizzle ORM integration, include these specific dependencies:

npm install drizzle-orm @neondatabase/serverless dotenv
npm install -D drizzle-kit

Neon Connection Configuration

• Always use the Neon connection string format:

DATABASE_URL=postgres://username:password@ep-instance-id.region.aws.neon.tech/neondb

• Store this in .env or .env.local file

Neon Connection Setup

When connecting to Neon specifically:

• Use the neon client from @neondatabase/serverless package
• Pass the connection string to create the SQL client
• Use drizzle with the neon-http adapter specifically

// src/db.ts
import { drizzle } from "drizzle-orm/neon-http";
import { neon } from "@neondatabase/serverless";
import { config } from "dotenv";

// Load environment variables
config({ path: ".env" });

if (!process.env.DATABASE_URL) {
  throw new Error("DATABASE_URL is not defined");
}

// Create Neon SQL client - specific to Neon
const sql = neon(process.env.DATABASE_URL);

// Create Drizzle instance with neon-http adapter
export const db = drizzle({ client: sql });

Neon Database Considerations

Default Settings

• Neon projects come with a ready-to-use database named neondb
• Default role is typically neondb_owner
• Connection strings include the correct endpoint based on your region

Serverless Optimization

Neon is optimized for serverless environments:

• Use the HTTP-based neon-http adapter instead of node-postgres
• Take advantage of connection pooling for serverless functions
• Consider Neon's auto-scaling capabilities when designing schemas

Schema Considerations for Neon

When defining schemas for Neon:

• Use Postgres-specific types from drizzle-orm/pg-core
• Leverage Postgres features that Neon supports:

- JSON/JSONB columns

- Full-text search

- Arrays

- Enum types

// src/schema.ts
import {
  pgTable,
  serial,
  text,
  integer,
  timestamp,
  jsonb,
  pgEnum,
} from "drizzle-orm/pg-core";

// Example of Postgres-specific enum with Neon
export const userRoleEnum = pgEnum("user_role", ["admin", "user", "guest"]);

export const usersTable = pgTable("users", {
  id: serial("id").primaryKey(),
  name: text("name").notNull(),
  email: text("email").notNull().unique(),
  role: userRoleEnum("role").default("user"),
  metadata: jsonb("metadata"), // Postgres JSONB supported by Neon
  // Other columns
});

// Export types
export type User = typeof usersTable.$inferSelect;
export type NewUser = typeof usersTable.$inferInsert;

Drizzle Config for Neon

Neon-specific configuration in drizzle.config.ts:

// drizzle.config.ts
import { config } from "dotenv";
import { defineConfig } from "drizzle-kit";

config({ path: ".env" });

export default defineConfig({
  schema: "./src/schema.ts",
  out: "./migrations",
  dialect: "postgresql", // Neon uses Postgres dialect
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
  // Optional: Neon project specific tables to include/exclude
  // includeTables: ['users', 'posts'],
  // excludeTables: ['_migrations'],
});

Neon-Specific Query Optimizations

Efficient Queries for Serverless

Optimize for Neon's serverless environment:

• Keep connections short-lived
• Use prepared statements for repeated queries
• Batch operations when possible

// Example of optimized query for Neon
import { db } from "../db";
import { sql } from "drizzle-orm";
import { usersTable } from "../schema";

export async function batchInsertUsers(users: NewUser[]) {
  // More efficient than multiple individual inserts on Neon
  return db.insert(usersTable).values(users).returning();
}

// For complex queries, use prepared statements
export const getUsersByRolePrepared = db
  .select()
  .from(usersTable)
  .where(sql`${usersTable.role} = $1`)
  .prepare("get_users_by_role");

// Usage: getUsersByRolePrepared.execute(['admin'])

Transaction Handling with Neon

Neon supports transactions through Drizzle:

import { db } from "../db";
import { usersTable, postsTable } from "../schema";

export async function createUserWithPosts(user: NewUser, posts: NewPost[]) {
  return await db.transaction(async (tx) => {
    const [newUser] = await tx.insert(usersTable).values(user).returning();

    if (posts.length > 0) {
      await tx.insert(postsTable).values(
        posts.map((post) => ({
          ...post,
          userId: newUser.id,
        })),
      );
    }

    return newUser;
  });
}

Working with Neon Branches

Neon supports database branching for development and testing:

```typescript

// Using different Neon branches with environment variables

impor