### Example Prompt: Get Started with Neon

Source: https://github.com/neondatabase/agent-skills/blob/main/README.md

An example prompt to get started with Neon.

```text
Get started with Neon
```

--------------------------------

### Example Prompt: Recommend Connection Method

Source: https://github.com/neondatabase/agent-skills/blob/main/README.md

An example prompt to get a recommendation for a connection method for a project.

```text
Recommend a connection method for this project
```

--------------------------------

### Example Prompt: Temporary Postgres Database

Source: https://github.com/neondatabase/agent-skills/blob/main/README.md

An example prompt to get a quick temporary Postgres database.

```text
Give me a quick temporary Postgres database
```

--------------------------------

### Example Prompt: Set up Drizzle ORM

Source: https://github.com/neondatabase/agent-skills/blob/main/README.md

An example prompt to set up Drizzle ORM with Neon.

```text
Set up Drizzle ORM with Neon
```

--------------------------------

### Example Prompt: Set up Neon Auth

Source: https://github.com/neondatabase/agent-skills/blob/main/README.md

An example prompt to set up Neon Auth for a Next.js application.

```text
Set up Neon Auth for my Next.js app
```

--------------------------------

### Example Prompt: Query with neon-js

Source: https://github.com/neondatabase/agent-skills/blob/main/README.md

An example prompt to query the database using neon-js.

```text
Query the database using neon-js
```

--------------------------------

### Install Neon Configuration Package

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/09-skills-index.md

Install the necessary package for Neon's infrastructure-as-code configuration.

```bash
npm install @neondatabase/config
```

--------------------------------

### Install Neon CLI Globally

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon/SKILL.md

Use this command to install the Neon CLI globally if you prefer not to use `npx`. This is an alternative to the `init` command for CLI installation.

```bash
npm i -g neonctl
```

--------------------------------

### Example Prompt: Use Serverless Driver

Source: https://github.com/neondatabase/agent-skills/blob/main/README.md

An example prompt to use the serverless driver for edge functions.

```text
Use the serverless driver for edge functions
```

--------------------------------

### Manage Neon Resources with TypeScript SDK

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/05-neon-postgres-api.md

Provides examples of using the @neondatabase/api-client to list projects, get project details, list branches, create a branch, and retrieve a connection string.

```typescript
import { Neon } from "@neondatabase/api-client";

const neon = new Neon({ apiKey: process.env.NEON_API_KEY });

// List projects
const projects = await neon.projects.list();

// Get a project
const project = await neon.projects.get("project-id");

// List branches
const branches = await project.branches.list();

// Create a branch
const branch = await project.branches.create({
  name: "feature/auth",
  parentId: "main",
});

// Get connection string
const connectionString = await branch.getConnectionString();
```

--------------------------------

### Install Neon CLI

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/09-skills-index.md

Install the Neon Command-line Interface globally or use npx for immediate execution. The CLI manages Neon resources.

```bash
npm install -g neonctl
# or
npx neonctl <command>
```

--------------------------------

### Example .env File Output

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/claimable-postgres/SKILL.md

Illustrates the output format written to the target .env file after successful provisioning.

```dotenv
DATABASE_URL=postgresql://...              # pooled (use for application queries)
DATABASE_URL_DIRECT=postgresql://...       # direct (use for migrations, e.g. Prisma)
PUBLIC_POSTGRES_CLAIM_URL=https://neon.new/claim/...
```

--------------------------------

### Example Prompt: Create Neon Branch via API

Source: https://github.com/neondatabase/agent-skills/blob/main/README.md

An example prompt to create a new Neon branch using the API.

```text
Create a new Neon branch using the API
```

--------------------------------

### Install Neon CLI

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/05-neon-postgres-api.md

Install the Neon CLI globally using npm or use it directly with npx.

```bash
npm install -g neonctl
# or use with npx
npx neonctl <command>
```

--------------------------------

### Install Neon Python SDK

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/09-skills-index.md

Install the Python package for interacting with the Neon API.

```bash
pip install neon-api
```

--------------------------------

### Install Vite Plugin

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/01-claimable-postgres-api.md

Install the `vite-plugin-neon-new` as a development dependency.

```bash
npm install -D vite-plugin-neon-new
```

--------------------------------

### Install Neon Env Package

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon/SKILL.md

Install the `@neondatabase/env` package using npm.

```bash
npm i @neondatabase/env
```

--------------------------------

### Configure New Branch Settings

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon/SKILL.md

Define custom configurations for new branches based on their properties. This example sets a 7-day TTL and a scale-to-zero compute profile for branches starting with 'dev'.

```typescript
// neon.ts
import { defineConfig } from "@neondatabase/config/v1";

export default defineConfig({
  auth: true,
  dataApi: true,
  branch: (branch) => {
    if (branch.exists) {
      // leave existing branches untouched
      return {};
    }
    if (branch.name.startsWith("dev")) {
      return {
        ttl: "7d", // clean up the branch after 7 days
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.25, // scale to zero
            autoscalingLimitMaxCu: 1, // keep it cheap
            suspendTimeout: "5m",
          },
        },
      };
    }
    return {};
  },
});
```

--------------------------------

### Install Neon PostgreSQL Branches Skill

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon-postgres/SKILL.md

Use this command to install the neon-postgres-branches skill if it is not already installed. This skill helps manage branch creation workflows.

```bash
npx skills add neondatabase/agent-skills --skill neon-postgres-branches
```

--------------------------------

### Install Neon TypeScript SDK

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/09-skills-index.md

Install the official TypeScript SDK for typed programmatic access to Neon resources.

```bash
npm install @neondatabase/api-client
```

--------------------------------

### Initialize Neon Project with Agent

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/09-skills-index.md

Initialize Neon in your project, which includes creating an API key and installing the necessary extension. Use the --agent flag to specify an agent.

```bash
neonctl init --agent <agent>
```

--------------------------------

### Add Neon MCP Server

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon/SKILL.md

Installs and configures the Neon MCP server globally. Use the `-n` flag to specify the agent name and `-y` for non-interactive setup.

```bash
npx -y add-mcp https://mcp.neon.tech/mcp -g -n Neon -y -a <agent-name>
```

--------------------------------

### Basic neon.ts Setup

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/08-neon-config-reference.md

Create the neon.ts file in your project root and export the defineConfig function.

```typescript
// neon.ts
import { defineConfig } from "@neondatabase/config/v1";

export default defineConfig({
  // ... config
});
```

--------------------------------

### Install Neon MCP Server

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/09-skills-index.md

Install the Model Context Protocol server globally for programmatic Neon access from agents and LLMs. Specify the agent name with the -n flag.

```bash
npx -y add-mcp https://mcp.neon.tech/mcp -g -n Neon -a <agent-name>
```

--------------------------------

### Initialize Neon Project with CLI

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon/SKILL.md

Run this command to install the Neon CLI and MCP server globally, add agent skills to your project, and set up VSCode extensions. It handles authentication automatically.

```bash
npx -y neonctl@latest init
```

--------------------------------

### Install Neon Local Connect Extension

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon/SKILL.md

Install the Neon local connect extension for Cursor or VS Code. This extension helps in connecting to local Neon services.

```bash
cursor --install-extension databricks.neon-local-connect
```

--------------------------------

### Install a Neon Agent Skill

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon/SKILL.md

Install a specific Neon agent skill using the 'skills' CLI. Replace <skill-name> with the desired skill, such as 'neon-object-storage'.

```bash
npx skills add neondatabase/agent-skills -s <skill-name>
```

--------------------------------

### Initialize Neon with Agent

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/05-neon-postgres-api.md

Use the Neon CLI to initialize Neon in your project with agent support. This command installs the CLI, creates an API key, and adds the specified agent skill.

```bash
npx -y neonctl@latest init --agent <agent-name>
```

--------------------------------

### Manage Neon Resources with Python SDK

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/05-neon-postgres-api.md

Demonstrates using the neon-api package in Python to list projects, create a branch, and get a connection string.

```python
from neon_api import Client

client = Client(api_key="YOUR_API_KEY")

# List projects
projects = client.projects.list()

# Create a branch
branch = client.projects.get("project-id").branches.create(
    name="feature/auth",
    parent_id="main"
)

# Get connection string
conn_str = branch.connection_string()
```

--------------------------------

### Install Neon Agent Skill with Flags

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon/SKILL.md

Install a Neon agent skill globally for a specific agent without interactive prompts. Use flags like -g for global install, -y for non-interactive mode, and -a for the target agent.

```bash
npx skills add neondatabase/agent-skills -s neon-object-storage -g -y -a <agent-name>
```

--------------------------------

### Install Agent Skills

Source: https://github.com/neondatabase/agent-skills/blob/main/README.md

Use this command to add the agent skills to your project.

```bash
npx skills add neondatabase/agent-skills
```

--------------------------------

### Basic WebSocket Server with ws and Token Authentication

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon-functions/SKILL.md

This example demonstrates a simple WebSocket server using the `ws` library. It handles plain HTTP requests with `fetch` and WebSocket handshakes with `upgrade`. Authentication is performed via a `?token=` query parameter before accepting the connection.

```typescript
// src/index.ts
import type { IncomingMessage } from "node:http";
import type { Duplex } from "node:stream";
import { WebSocketServer, type WebSocket } from "ws";

const clients = new Set<WebSocket>();
const wss = new WebSocketServer({ noServer: true });

export default {
  // Plain HTTP (health checks, REST) is handled by fetch.
  fetch: () => new Response("WebSocket endpoint — connect with ?token=<jwt>"),

  // The runtime hands the WebSocket handshake to upgrade().
  async upgrade(req: IncomingMessage, socket: Duplex, head: Buffer) {
    const url = new URL(req.url ?? "/", "http://localhost");
    const identity = await verifyToken(url.searchParams.get("token")); // reject if invalid
    if (!identity) {
      socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
      socket.destroy();
      return;
    }
    wss.handleUpgrade(req, socket, head, (ws) => {
      clients.add(ws);
      ws.on("close", () => clients.delete(ws));
      ws.on("message", (data) => broadcast(data.toString())); // see fan-out below
    });
  },
};
```

--------------------------------

### Non-interactive Neon Initialization

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/05-neon-postgres-api.md

Perform a non-interactive setup for Neon, first by adding the MCP server and then by adding the agent skill. This is useful for automated or scripted environments.

```bash
# MCP server (for most agents)
npx -y add-mcp https://mcp.neon.tech/mcp -g -n Neon -y -a <agent-name>
```

```bash
# Agent skill
npx skills add neondatabase/agent-skills --skill neon-postgres --agent <agent-name> -y
```

--------------------------------

### Switch to a Feature Branch

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/06-neon-postgres-branches-api.md

Checkout a specific feature branch to start development. If Neon Functions are configured, they will be deployed to this branch.

```bash
neonctl checkout preview/feature-x
```

--------------------------------

### Run Local Development Server with Hot Reload

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/08-neon-config-reference.md

Start the Neon local development server which serves functions with hot reload and injects environment variables.

```bash
neonctl dev  # serves functions with hot reload, injects vars
```

--------------------------------

### Simple WebSocket Server with `ws` Library

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/03-neon-functions-api.md

Implement a basic WebSocket server using the `ws` library. This example includes JWT authentication for incoming connections and broadcasts messages using PostgreSQL's `pg_notify`.

```typescript
import { WebSocketServer, type WebSocket } from "ws";
import { createRemoteJWKSet, jwtVerify } from "jose";

const clients = new Set<WebSocket>();
const wss = new WebSocketServer({ noServer: true });
const jwks = createRemoteJWKSet(new URL(`${process.env.AUTH_BASE_URL}/api/auth/jwks`));

export default {
  fetch: () => new Response("WebSocket endpoint — connect with ?token=<jwt>"),

  async upgrade(req: IncomingMessage, socket: Duplex, head: Buffer) {
    const url = new URL(req.url ?? "/", "http://localhost");
    const token = url.searchParams.get("token");

    // Authenticate
    if (!token) {
      socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
      socket.destroy();
      return;
    }

    try {
      const { payload } = await jwtVerify(token, jwks, {
        issuer: process.env.AUTH_BASE_URL,
        audience: process.env.AUTH_BASE_URL,
      });
      const userId = payload.sub;

      wss.handleUpgrade(req, socket, head, (ws) => {
        clients.add(ws);
        ws.on("close", () => clients.delete(ws));
        ws.on("message", (data) => {
          // Broadcast via LISTEN/NOTIFY (see Fan-Out section)
          pool.query("SELECT pg_notify('chat_events', $1)", [data]);
        });
      });
    } catch {
      socket.write("HTTP/1.1 401 Unauthorized\r\n\r\n");
      socket.destroy();
    }
  },
};
```

--------------------------------

### Hono WebSocket Setup and Authentication

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon-functions/references/hono-websockets.md

Demonstrates setting up a Hono application with WebSocket support, including middleware for token verification before upgrading the connection. This is useful for securing WebSocket endpoints.

```typescript
import { Hono } from "hono";
import { createNeonWebSocket } from "./hono-ws";

const app = new Hono();
const { upgradeWebSocket, handler } = createNeonWebSocket(app);

app.get("/", (c) => c.text("ok"));

app.get(
  "/ws",
  async (c, next) => {
    const identity = await verifyToken(c.req.query("token")); // your JWT check
    if (!identity) return c.text("Unauthorized", 401);
    await next();
  },
  upgradeWebSocket(() => ({
    onOpen: (_evt, ws) => ws.send("welcome"),
    onMessage: (evt, ws) => ws.send(`echo: ${evt.data}`),
    onClose: () => console.log("disconnected"),
  })),
);

export default handler; // Neon's { fetch, upgrade } contract
```

--------------------------------

### Develop and Test Application on Feature Branch

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/06-neon-postgres-branches-api.md

Set the DATABASE_URL environment variable for the feature branch and start the development server. This allows for local testing of application logic and database interactions.

```bash
export DATABASE_URL=$(neonctl connection-string --branch-id preview/feature-x)
npm run dev
```

--------------------------------

### Install Skill Locally with Claude Code

Source: https://github.com/neondatabase/agent-skills/blob/main/CLAUDE.md

Command to copy a skill directory into the local Claude skills directory for development or testing.

```bash
cp -r skills/{skill-name} ~/.claude/skills/
```

--------------------------------

### Minimal Hono + Drizzle + Postgres Example

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/03-neon-functions-api.md

A basic Hono application demonstrating how to connect to a PostgreSQL database using Drizzle ORM and perform CRUD operations on a 'todos' table. Ensure you have the necessary environment variables and schema defined.

```typescript
// src/index.ts
import { Hono } from "hono";
import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import { parseEnv } from "@neondatabase/env/v1";
import config from "../neon";
import { todos } from "./db/schema";

const env = parseEnv(config);
const pool = new Pool({ connectionString: env.postgres.databaseUrl, max: 5 });
const db = drizzle(pool);

const app = new Hono();

app.get("/", (c) => c.text("Neon Functions + Hono + Drizzle"));

app.get("/todos", async (c) => {
  const rows = await db.select().from(todos);
  return c.json(rows);
});

app.post("/todos", async (c) => {
  const { text } = await c.req.json<{ text: string }>();
  const [row] = await db.insert(todos).values({ text }).returning();
  return c.json(row, 201);
});

export default app;
```

--------------------------------

### Multi-Provider Routing with Neon AI SDK Provider

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon-ai-gateway/SKILL.md

This example demonstrates multi-provider routing from a single call using the dedicated `@neondatabase/ai-sdk-provider`. It reads gateway credentials and routes models to the appropriate endpoints.

```typescript
import { neon } from "@neondatabase/ai-sdk-provider/v1";
import { generateText } from "ai";

const { text } = await generateText({
  model: neon("claude-haiku-4-5"), // or gpt-5-3-codex, gemini-2-5-flash, ...
  prompt: "Summarize Postgres for me.",
});
```

--------------------------------

### Provision Database with Defaults

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/claimable-postgres/SKILL.md

Provisions a database and writes the connection string to .env in one step. Use @latest and --yes to skip interactive prompts.

```bash
npx neon-new@latest --yes
```

--------------------------------

### Initialize Instant Postgres with SDK

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/claimable-postgres/SKILL.md

Use the SDK for programmatic database provisioning. The `referrer` parameter is required. This returns pooled and direct database URLs, along with a claim URL and expiration date.

```typescript
import { instantPostgres } from "neon-new";

const { databaseUrl, databaseUrlDirect, claimUrl, claimExpiresAt } =
  await instantPostgres({
    referrer: "agent-skills",
    seed: { type: "sql-script", path: "./init.sql" },
  });
```

--------------------------------

### Type Error: Data API Requires Neon Auth

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon/SKILL.md

Illustrates a type error when enabling the Data API without explicitly enabling Neon Auth, which is its default provider. The compiler error guides on valid setups.

```typescript
export default defineConfig({
  dataApi: true, // type error: `dataApi` (default authProvider 'neon') requires Neon Auth
});
```

--------------------------------

### Alternative Package Manager Commands

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/claimable-postgres/SKILL.md

Shows alternative commands for provisioning a database using different package managers.

```bash
yarn dlx neon-new@latest
```

```bash
pnpm dlx neon-new@latest
```

```bash
bunx neon-new@latest
```

```bash
deno run -A neon-new@latest
```

--------------------------------

### Provision Database with CLI Tool

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/claimable-postgres/SKILL.md

Execute the `neon-new` CLI tool to provision a database, specifying options like reference, environment file, and seed script. Always use `@latest` and `--yes` for agent workflows.

```bash
npx neon-new@latest --yes --ref agent-skills --env .env.local --seed ./schema.sql
```

--------------------------------

### Example Prompt: High Neon Bill

Source: https://github.com/neondatabase/agent-skills/blob/main/README.md

An example prompt to diagnose why a Neon bill might be high.

```text
Why is my Neon bill so high?
```

--------------------------------

### Neon CLI: Manage Projects

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/05-neon-postgres-api.md

Commands to list, create, and set the default project.

```bash
neonctl projects list                  # list projects in the org
neonctl projects create --name foo     # create a project
neonctl project set <project-id>       # set the default project
```

--------------------------------

### Example Error Response

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/02-neon-ai-gateway-api.md

This is an example of an error response returned by the Neon AI Gateway API. It follows the OpenAI-compatible error format.

```json
{
  "error": {
    "message": "Invalid model",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}
```

--------------------------------

### instantPostgres()

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/01-claimable-postgres-api.md

Programmatically provisions a temporary PostgreSQL database. It accepts an options object to configure the database, including a referrer for tracking, an optional SQL script to seed the database, and a flag to enable logical replication.

```APIDOC
## Function: `instantPostgres()`

Programmatically provision a temporary database.

### Parameters

#### Options Object

- **`referrer`** (string) - Required - Tracking identifier. Use `"agent-skills"` when provisioning through the skill.
- **`seed`** (object) - Optional - Used to seed the database with data.
  - **`seed.type`** (string) - Optional - Always `"sql-script"` if present.
  - **`seed.path`** (string) - Optional - Path to SQL file to execute after creation.
- **`enableLogicalReplication`** (boolean) - Optional - Enable logical replication. Cannot be disabled once enabled. Defaults to `false`.

### Return Value

An object containing connection URLs and claim information for the provisioned database.

- **`databaseUrl`** (string) - Pooled PostgreSQL connection URL (routed through connection pooler). Use for application queries.
- **`databaseUrlDirect`** (string) - Direct PostgreSQL connection URL. Use for migrations and transactions that require a real session.
- **`claimUrl`** (string) - HTTPS URL to claim this database in a browser. Valid for 72 hours.
- **`claimExpiresAt`** (Date) - JavaScript Date object representing the expiration time.

### Example

```typescript
import { instantPostgres } from "neon-new";

const { databaseUrl, databaseUrlDirect, claimUrl, claimExpiresAt } = await instantPostgres({
  referrer: "agent-skills",
  seed: { type: "sql-script", path: "./init.sql" },
});

console.log("Database ready:", databaseUrl);
console.log("Claim before:", claimExpiresAt);
```
```

--------------------------------

### Provision Temporary Database with CLI

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/01-claimable-postgres-api.md

Use this command to provision a temporary database and automatically write connection strings to a specified .env file. It's useful for quickly setting up development databases.

```bash
npx neon-new@latest [OPTIONS]
```

```bash
npx neon-new@latest --yes --ref agent-skills --seed ./schema.sql --env .env.local
```

--------------------------------

### Install Claude Code Plugin

Source: https://github.com/neondatabase/agent-skills/blob/main/README.md

Commands to install the Neon agent skills as a Claude Code plugin. This bundles Neon skills and the Neon MCP Server.

```bash
/plugin marketplace add neondatabase/agent-skills
/plugin install neon-postgres@neon
```

--------------------------------

### Provision Object Storage Buckets

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon-object-storage/SKILL.md

Use the `neonctl deploy` command to provision the object storage buckets declared in your `neon.ts` configuration file.

```bash
neonctl deploy   # alias for `neonctl config apply`
```

--------------------------------

### Neon CLI: Manage Configuration

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/05-neon-postgres-api.md

Commands to check configuration status, plan, and apply changes.

```bash
neonctl config status   # show live branch config
neonctl config plan     # dry-run diff of neon.ts
neonctl config apply    # deploy neon.ts
neonctl deploy          # alias for config apply
```

--------------------------------

### Neon Function + Hono + Drizzle Example

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/README.md

Minimal example of a Neon Function using Hono and Drizzle ORM to interact with a PostgreSQL database. Configures a connection pool with a maximum of 5 connections.

```typescript
import { Hono } from "hono";
import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";

const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
const db = drizzle(pool);
const app = new Hono();

app.get("/todos", async (c) => c.json(await db.select().from(todos)));

export default app;
```

--------------------------------

### Link Local Workspace to Neon Project

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon/SKILL.md

Run this command to interactively link your local workspace to a Neon project. This creates a `.neon` file that stores configuration details for your organization, project, and branch.

```bash
npx -y neonctl link
```

--------------------------------

### Get Connection String using Neon REST API

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/06-neon-postgres-branches-api.md

Retrieve the PostgreSQL connection string for a specific branch by sending a GET request to the Neon REST API. Requires project and branch IDs, and an API key.

```http
GET /api/v2/projects/{project_id}/branches/{branch_id}/connection_string
Authorization: Bearer {api_key}
```

--------------------------------

### Get Branch Details using Neon REST API

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/06-neon-postgres-branches-api.md

Retrieve detailed information for a specific branch by sending a GET request to the Neon REST API, using the project and branch IDs. Requires an API key.

```http
GET /api/v2/projects/{project_id}/branches/{branch_id}
Authorization: Bearer {api_key}
```

--------------------------------

### GET Object

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/04-neon-object-storage-api.md

Download a file from the S3 bucket using its key.

```APIDOC
## GET Object

### Description
Download a file from the bucket.

### Method
GET

### Endpoint
`/objects/{key}` (Assumed based on S3 GET Object operation)

### Parameters
#### Path Parameters
- **key** (string) - Required - Object path within the bucket.

#### Query Parameters
None

#### Request Body
None

### Request Example
(No request body example provided)

### Response
#### Success Response (200)
- **Body** (Buffer or Stream) - The content of the downloaded object.

#### Response Example
(No specific response example provided)
```

--------------------------------

### Use Neon Python SDK to List Projects

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/09-skills-index.md

Initialize the Neon API client with your API key and retrieve a list of your projects.

```python
from neon_api import Client

client = Client(api_key="YOUR_API_KEY")
projects = client.projects.list()
```

--------------------------------

### Get Function Details

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/03-neon-functions-api.md

Retrieves the invocation URL and deployment metadata for a specific function.

```bash
neonctl functions get <slug>
```

--------------------------------

### Neon CLI for Configuration Management

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/05-neon-postgres-api.md

Manage your Neon infrastructure using the `neonctl` command-line tool. Commands include checking configuration status, planning changes, and applying them to provision services.

```bash
neonctl config status   # print the branch's live config
neonctl config plan     # dry-run diff of neon.ts vs. live
neonctl config apply    # provision the declared services
neonctl deploy          # alias for config apply
```

--------------------------------

### Get Project Details

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/05-neon-postgres-api.md

Retrieves detailed information about a specific project using its ID.

```APIDOC
## GET /api/v2/projects/{project_id}

### Description
Retrieves detailed information about a specific project.

### Method
GET

### Endpoint
/api/v2/projects/{project_id}

#### Path Parameters
- **project_id** (string) - Required - The unique identifier of the project.
```

--------------------------------

### TypeScript SDK - Get Project

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/05-neon-postgres-api.md

Uses the TypeScript SDK to retrieve details for a specific project.

```typescript
import { Neon } from "@neondatabase/api-client";

const neon = new Neon({ apiKey: process.env.NEON_API_KEY });

// Get a project
const project = await neon.projects.get("project-id");
```

--------------------------------

### SQL: Reset Statistics

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/07-neon-egress-optimizer-api.md

Reset query statistics using `pg_stat_statements_reset()` to start fresh after optimization efforts.

```sql
SELECT pg_stat_statements_reset()
```

--------------------------------

### Claimable Postgres SDK Initialization

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/README.md

Initializes the Claimable Postgres SDK to obtain database and claim URLs.

```typescript
import { instantPostgres } from "neon-new";

const { databaseUrl, databaseUrlDirect, claimUrl } = 
  await instantPostgres({ referrer: "agent-skills" });
```

--------------------------------

### Get Connection String for a Neon Branch

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon-postgres-branches/SKILL.md

Fetches the connection string for a specified branch, useful after branch creation for accessing the new branch.

```bash
neonctl connection-string <branch-name>
```

--------------------------------

### Create Index for Filtering

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/07-neon-egress-optimizer-api.md

Create composite indexes to optimize queries that filter on multiple columns. This example indexes 'user_id' and 'created_at' for efficient lookups.

```sql
CREATE INDEX idx_activity_logs_user_created
  ON activity_logs(user_id, created_at);
```

--------------------------------

### Neon CLI Commands

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/README.md

Commands for initializing, managing projects and branches, and deploying applications using the Neon CLI.

```bash
neonctl init --agent <agent-name>
neonctl projects list
neonctl branches create --name <name>
neonctl checkout <branch-id>
neonctl connection-string [--branch-id <id>]
neonctl env pull
neonctl dev
neonctl deploy
neonctl config status
neonctl functions list|get|delete <slug>
```

--------------------------------

### Get Connection String for Migration Test Branch

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/neon-postgres-branches/SKILL.md

Retrieve the connection string for a specific Neon branch, useful after creating a branch for migration testing.

```bash
neonctl connection-string migration-test
```

--------------------------------

### GET /database/{id}

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/01-claimable-postgres-api.md

Retrieves the status of an existing temporary PostgreSQL database using its unique identifier. The `connection_string` will be null if the database has already been claimed.

```APIDOC
## GET /database/{id}

### Description
Check the status of an existing database. The `connection_string` will be null if the database has already been claimed.

### Method
GET

### Endpoint
https://neon.new/api/v1/database/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - Database ID returned by POST /database.

### Response
#### Success Response (200)
Same shape as POST response. `connection_string` is `null` after the database is claimed.

#### Response Example
```json
{
  "id": "019beb39-37fb-709d-87ac-7ad6198b89f7",
  "status": "UNCLAIMED",
  "neon_project_id": "gentle-scene-06438508",
  "connection_string": "postgresql://user:pass@ep-123-pooler.us-east-2.aws.neon.tech/neondb",
  "claim_url": "https://neon.new/claim/019beb39-37fb-709d-87ac-7ad6198b89f7",
  "expires_at": "2026-01-26T14:19:14.580Z",
  "created_at": "2026-01-23T14:19:14.580Z",
  "updated_at": "2026-01-23T14:19:14.580Z"
}
```

#### Throws
- **400** - `Database not found` - ID does not exist or has been deleted.
```

--------------------------------

### Per-Branch Function Configuration

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/03-neon-functions-api.md

Demonstrates how to configure Neon Functions differently for specific branches. This example sets a custom runtime for the 'todos' function on non-default branches.

```typescript
export default defineConfig({
  preview: {
    functions: {
      todos: { name: "todo api", source: "src/index.ts" },
    },
  },
  branch: (branch) => {
    if (branch.isDefault) return {}; // prod: default settings
    return {
      // dev/preview: custom settings
      preview: {
        functions: {
          todos: { runtime: "nodejs24" }, // specific branch config
        },
      },
    };
  },
});
```

--------------------------------

### Get Neon Connection String

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/05-neon-postgres-api.md

Retrieve the full PostgreSQL connection URL for a specific branch using the Neon CLI. This URL can be used to connect to your database.

```bash
neonctl connection-string --branch-id <branch-id>
```

--------------------------------

### Neonctl Configuration Commands

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/08-neon-config-reference.md

Commands for viewing, planning, and applying Neon configurations. Use `status` to view live config, `plan` for a dry-run diff, and `apply` or `deploy` to deploy.

```bash
# View live branch config
neonctl config status
```

```bash
# Dry-run diff of neon.ts vs. live
neonctl config plan
```

```bash
# Apply neon.ts to branch (deploy)
neonctl config apply
```

```bash
# Alias for config apply
neonctl deploy
```

--------------------------------

### Get Connection String for a Branch

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/06-neon-postgres-branches-api.md

Retrieve the database connection string for a specified branch. This is often needed to configure applications or run database tools against that branch.

```bash
neonctl connection-string --branch-id migration-test
```

--------------------------------

### Neon Database Creation Response

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/claimable-postgres/SKILL.md

This is a sample JSON response after successfully creating a database. It contains the database ID, status, project ID, connection strings, and claim information.

```json
{
  "id": "019beb39-37fb-709d-87ac-7ad6198b89f7",
  "status": "UNCLAIMED",
  "neon_project_id": "gentle-scene-06438508",
  "connection_string": "postgresql://...",
  "claim_url": "https://neon.new/claim/019beb39-...",
  "expires_at": "2026-01-26T14:19:14.580Z",
  "created_at": "2026-01-23T14:19:14.580Z",
  "updated_at": "2026-01-23T14:19:14.580Z"
}
```

--------------------------------

### Get Connection String (MCP Server)

Source: https://github.com/neondatabase/agent-skills/blob/main/_autodocs/06-neon-postgres-branches-api.md

Retrieves the PostgreSQL connection URL for a specific branch via the Neon MCP Server. Used by agents and LLMs.

```APIDOC
## Get Connection String (MCP Server)

### Description
Retrieves the PostgreSQL connection URL for a specific branch via the Neon MCP Server. Used by agents and LLMs.

### Tool
`get_connection_string`

### Parameters

#### Request Body

* `branch_id` (string) - Required - The ID of the branch.
```

--------------------------------

### Create a database

Source: https://github.com/neondatabase/agent-skills/blob/main/skills/claimable-postgres/SKILL.md

Provisions a new database. The `connection_string` returned can be used to connect to the database. For direct connections (e.g., Prisma migrations), remove `-pooler` from the hostname.

```APIDOC
## POST /database

### Description
Provisions a new database.

### Method
POST

### Endpoint
/database

### Parameters
#### Request Body
- **ref** (string) - Required - Tracking tag that identifies who provisioned the database. Use `"agent-skills"` when provisioning through this skill.
- **enable_logical_replication** (boolean) - Optional - Enable logical replication (default: false, cannot be disabled once enabled).

### Request Example
```json
{
  "ref": "agent-skills"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the database.
- **status** (string) - The current status of the database (e.g., `UNCLAIMED`, `CLAIMING`, `CLAIMED`).
- **neon_project_id** (string) - The Neon project ID associated with the database.
- **connection_string** (string) - The pooled connection URL for the database.
- **claim_url** (string) - A URL to claim the database.
- **expires_at** (string) - The timestamp when the database will expire.
- **created_at** (string) - The timestamp when the database was created.
- **updated_at** (string) - The timestamp when the database was last updated.

#### Response Example
```json
{
  "id": "019beb39-37fb-709d-87ac-7ad6198b89f7",
  "status": "UNCLAIMED",
  "neon_project_id": "gentle-scene-06438508",
  "connection_string": "postgresql://...",
  "claim_url": "https://neon.new/claim/019beb39-...",
  "expires_at": "2026-01-26T14:19:14.580Z",
  "created_at": "2026-01-23T14:19:14.580Z",
  "updated_at": "2026-01-23T14:19:14.580Z"
}
```
```